Browserwing Admin

macOS

brew install --cask google-chrome

Windows

Download and install from: https://www.google.com/chrome/

Verify Installation

google-chrome --version
# or on macOS:
# /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version

Using Remote Chrome (Alternative)

If Chrome is running on a remote machine with debugging enabled:

google-chrome --remote-debugging-port=9222 --remote-debugging-address=0.0.0.0 --no-sandbox

Then configure BrowserWing's config.toml:

[browser]
control_url = 'http://<remote-host>:9222'

2. LLM Configuration

AI features (AI Explorer, Agent chat, smart extraction) require an LLM configuration.

List LLM Configs

curl -X GET 'http://localhost:8080/api/v1/llm-configs'

Add LLM Config

curl -X POST 'http://localhost:8080/api/v1/llm-configs' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-openai",
    "provider": "openai",
    "api_key": "sk-xxx",
    "model": "gpt-4o",
    "base_url": "https://api.openai.com/v1",
    "is_active": true,
    "is_default": true
  }'

Supported providers: openai, anthropic, deepseek, or any OpenAI-compatible endpoint.

Test LLM Config

curl -X POST 'http://localhost:8080/api/v1/llm-configs/test' \
  -H 'Content-Type: application/json' \
  -d '{"name": "my-openai"}'

Update LLM Config

curl -X PUT 'http://localhost:8080/api/v1/llm-configs/<config-id>' \
  -H 'Content-Type: application/json' \
  -d '{"api_key": "sk-new-key", "model": "gpt-4o-mini"}'

Delete LLM Config

curl -X DELETE 'http://localhost:8080/api/v1/llm-configs/<config-id>'

3. AI Autonomous Exploration (Generate Scripts Automatically)

Use AI to browse a website, perform a task, and automatically generate a replayable script.

Start Exploration

curl -X POST 'http://localhost:8080/api/v1/ai-explore/start' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_desc": "Go to bilibili.com, search for 'AI', and get the first page of video results",
    "start_url": "https://www.bilibili.com",
    "llm_config_id": "my-openai"
  }'

Response: Returns a session id for tracking.

Stream Exploration Events (SSE)

curl -N 'http://localhost:8080/api/v1/ai-explore/<session-id>/stream'

Returns real-time Server-Sent Events: thinking, tool_call, progress, error, script_ready, done.

Stop Exploration

curl -X POST 'http://localhost:8080/api/v1/ai-explore/<session-id>/stop'

Get Generated Script

curl -X GET 'http://localhost:8080/api/v1/ai-explore/<session-id>/script'

Save Generated Script

curl -X POST 'http://localhost:8080/api/v1/ai-explore/<session-id>/save'

Saves the generated script to the local script library for future replay.

4. Script Management

List All Scripts

curl -X GET 'http://localhost:8080/api/v1/scripts'

Returns all local scripts with their id, name, description, actions, tags, group, etc.

Get Script Details

curl -X GET 'http://localhost:8080/api/v1/scripts/<script-id>'

Get Script Schema / Summary

curl -X GET 'http://localhost:8080/api/v1/scripts/summary'

Returns a concise summary of all scripts, including names, descriptions, input parameters (variables), and action counts. Useful for programmatic discovery.

Create a New Script

curl -X POST 'http://localhost:8080/api/v1/scripts' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Search Bilibili",
    "description": "Search for a keyword on Bilibili",
    "url": "https://www.bilibili.com",
    "actions": [
      {"type": "navigate", "url": "https://www.bilibili.com"},
      {"type": "click", "identifier": ".nav-search-input"},
      {"type": "type", "identifier": ".nav-search-input", "value": "${keyword}"},
      {"type": "press_key", "key": "Enter"},
      {"type": "wait", "timeout": 3}
    ]
  }'

Variables: Use ${variable_name} syntax in action values. These become input parameters when the script is executed.

Update a Script

curl -X PUT 'http://localhost:8080/api/v1/scripts/<script-id>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Updated Name", "description": "Updated description"}'

Delete a Script

curl -X DELETE 'http://localhost:8080/api/v1/scripts/<script-id>'

Export Scripts as Skill (Convert to SKILL.md)

Convert one or more scripts into a SKILL.md file that can be imported by AI agents (e.g., Claude, Cursor). This allows other AI agents to discover and execute your BrowserWing scripts.

Export Selected Scripts

curl -X POST 'http://localhost:8080/api/v1/scripts/export/skill' \
  -H 'Content-Type: application/json' \
  -d '{
    "script_ids": ["script-id-1", "script-id-2", "script-id-3"]
  }'

Merges multiple scripts into a single SKILL.md with all their actions, variables, and descriptions.

Export All Scripts

curl -X POST 'http://localhost:8080/api/v1/scripts/export/skill' \
  -H 'Content-Type: application/json' \
  -d '{"script_ids": []}'

Pass an empty script_ids array to export all scripts into one SKILL.md.

Export Executor Skill (Browser Control API)

curl -X GET 'http://localhost:8080/api/v1/executor/export/skill'

Exports the low-level browser automation API as a skill, allowing an AI agent to directly control the browser (navigate, click, type, extract, etc.).

Workflow: Script → Skill → AI Agent

1. Create scripts (manually, by recording, or via AI exploration)
2. Export them as SKILL.md: POST /scripts/export/skill
3. Place the SKILL.md in your AI agent's skill directory
4. The AI agent can now discover and call your scripts via POST /scripts/<id>/play

5. Execute Scripts

Run a Script by ID

curl -X POST 'http://localhost:8080/api/v1/scripts/<script-id>/play' \
  -H 'Content-Type: application/json' \
  -d '{
    "variables": {
      "keyword": "deepseek"
    }
  }'

Variables: Pass values for ${variable_name} placeholders defined in the script actions.

Get Play Result (Extracted Data)

curl -X GET 'http://localhost:8080/api/v1/scripts/play/result'

Returns data extracted during the last script execution (e.g., scraped content from execute_js actions).

List Script Execution History

curl -X GET 'http://localhost:8080/api/v1/script-executions?page=1&page_size=20'

6. Script Marketplace (Remote Scripts)

Note: The remote script marketplace feature is under development. The following APIs may not be available yet.

Browse Marketplace

# TODO: curl -X GET 'http://localhost:8080/api/v1/marketplace/scripts?category=search&page=1'

Install Script from Marketplace

# TODO: curl -X POST 'http://localhost:8080/api/v1/marketplace/scripts/<remote-id>/install'

7. MCP (Model Context Protocol) Integration

BrowserWing exposes an MCP-compatible endpoint for AI agent integrations.

MCP SSE Endpoint

SSE:     http://localhost:8080/api/v1/mcp/sse
Message: http://localhost:8080/api/v1/mcp/sse_message

Check MCP Status

curl -X GET 'http://localhost:8080/api/v1/mcp/status'

List MCP Commands

curl -X GET 'http://localhost:8080/api/v1/mcp/commands'

Shows all registered MCP tools (browser tools + script-based custom commands).

8. Prompt Management

System prompts control AI behavior. Users can customize them.

List All Prompts

curl -X GET 'http://localhost:8080/api/v1/prompts'

Get a Specific Prompt

curl -X GET 'http://localhost:8080/api/v1/prompts/<prompt-id>'

System prompt IDs: system-extractor, system-formfiller, system-aiagent, system-get-mcp-info, system-ai-explorer

Update a Prompt

curl -X PUT 'http://localhost:8080/api/v1/prompts/<prompt-id>' \
  -H 'Content-Type: application/json' \
  -d '{"content": "Your custom prompt content here..."}'

9. Browser Instance Management

List Browser Instances

curl -X GET 'http://localhost:8080/api/v1/browser/instances'

Start a Browser Instance

curl -X POST 'http://localhost:8080/api/v1/browser/instances/<id>/start'

Stop a Browser Instance

curl -X POST 'http://localhost:8080/api/v1/browser/instances/<id>/stop'

10. Cookie Management

Manage browser cookies — view saved cookies, import cookies (e.g., for authenticated sessions), and delete cookies.

View Saved Cookies

curl -X GET 'http://localhost:8080/api/v1/cookies/browser'

Returns all cookies saved under the browser store ID (the default store). Replace browser with a custom store ID if needed.

Save Current Browser Cookies

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/save'

Saves all cookies from the current browser session to the database. Requires the browser to be running.

Import Cookies

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/import' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "cookies": [
      {
        "name": "session_id",
        "value": "abc123",
        "domain": ".example.com",
        "path": "/",
        "secure": true,
        "httpOnly": true,
        "sameSite": "Lax",
        "expires": 1735689600
      }
    ]
  }'

Fields: name and value are required. domain, path, secure, httpOnly, sameSite, expires are optional (path defaults to /).

Delete a Single Cookie

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/delete' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "browser",
    "name": "session_id",
    "domain": ".example.com",
    "path": "/"
  }'

Deletes a specific cookie identified by name + domain + path from the given cookie store.

Batch Delete Cookies

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/batch/delete' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "browser",
    "cookies": [
      {"name": "session_id", "domain": ".example.com", "path": "/"},
      {"name": "tracking", "domain": ".example.com", "path": "/"}
    ]
  }'

Deletes multiple cookies at once. Each cookie is identified by name + domain + path.

11. Troubleshooting

When something goes wrong, follow these steps to diagnose issues.

Check Service Health

curl -X GET 'http://localhost:8080/health'

View Logs

BrowserWing logs are stored in the path configured in config.toml under [log] file. Default location: ./log/browserwing.log

# View last 100 lines of logs
tail -n 100 ./log/browserwing.log

# Follow logs in real-time
tail -f ./log/browserwing.log

# Search for errors
grep -i 'error\|fail\|panic' ./log/browserwing.log | tail -20

Common Issues

1. Browser won't start

• Check if Google Chrome is installed: google-chrome --version
• On Linux, ensure --no-sandbox flag or run as non-root
• Check for lingering Chrome lock files in user data dir (SingletonLock, lockfile)
• If using remote Chrome, verify the control_url in config.toml
• Try killing existing Chrome processes: pkill -f chrome

2. AI features not working

• Ensure LLM config is set up and active: GET /api/v1/llm-configs
• Test the LLM connection: POST /api/v1/llm-configs/test
• Check API key validity and model availability
• Check logs for LLM-related errors

3. Script execution fails

• Verify the script exists: GET /api/v1/scripts/<id>
• Check if the browser is running: GET /api/v1/browser/instances
• Review execution history: GET /api/v1/script-executions
• Ensure all required ${variables} are provided in the play request
• Target website may have changed — try re-recording or updating the script

4. Page elements not found

• Use GET /api/v1/executor/snapshot to see current page elements
• Elements may have dynamic selectors — prefer RefIDs from snapshot
• Page may not have finished loading — use wait actions

5. Port conflicts

• BrowserWing default port: 8080 (configurable in config.toml under [server] port)
• Chrome debugging port: 9222 (or as configured in control_url)
• Check for port usage: lsof -i :<port> or netstat -tlnp | grep <port>

Quick Start Workflow

Here's how to get up and running:

1. Install Chrome (see Section 1)
2. Start BrowserWing: ./browserwing --port 8080
3. Add an LLM config (see Section 2)
4. Choose your approach:
   a) AI Exploration: POST /ai-explore/start with a task description
   b) Manual Creation: POST /scripts with actions array
   c) Web UI: Open http://<host>:8080 in browser to use the visual editor
5. Execute scripts: POST /scripts/<id>/play
6. View results: GET /scripts/play/result

API Quick Reference