BrowserWing Admin — Управление и автоматизация AI memory OS

--- name: browserwing-admin description: Manage and operate BrowserWing — an intelligent browser automation platform. Install dependencies, configure LLM, create/manage/execute automation scripts, use AI-driven exploration to generate scripts, browse the script marketplace, and troubleshoot issues. --- # BrowserWing Admin Skill ## Overview BrowserWing is an intelligent browser automation platform that allows you to: - Record, create, and replay browser automation scripts - Use AI to autonomously explore websites and generate replayable scripts - Execute scripts via HTTP API or MCP protocol - Manage LLM configurations for AI-powered features **API Base URL:** `http://localhost:8080/api/v1` **Authentication:** Use `X-BrowserWing-Key: <api-key>` header or `Authorization: Bearer <token>` --- ## 1. Installing Google Chrome (Prerequisite) BrowserWing requires Google Chrome to be installed on the host machine. ### Linux (Debian/Ubuntu) ```bash wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add - echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list sudo apt-get update sudo apt-get install -y google-chrome-stable ``` ### macOS ```bash brew install --cask google-chrome ``` ### Windows Download and install from: https://www.google.com/chrome/ ### Verify Installation ```bash 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: ```bash google-chrome --remote-debugging-port=9222 --remote-debugging-address=0.0.0.0 --no-sandbox ``` Then configure BrowserWing's `config.toml`: ```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 ```bash curl -X GET 'http://localhost:8080/api/v1/llm-configs' ``` ### Add LLM Config ```bash 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 ```bash curl -X POST 'http://localhost:8080/api/v1/llm-configs/test' -H 'Content-Type: application/json' -d '{"name": "my-openai"}' ``` ### Update LLM Config ```bash 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 ```bash 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 ```bash 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) ```bash 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 ```bash curl -X POST 'http://localhost:8080/api/v1/ai-explore/<session-id>/stop' ``` ### Get Generated Script ```bash curl -X GET 'http://localhost:8080/api/v1/ai-explore/<session-id>/script' ``` ### Save Generated Script ```bash 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 ```bash 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 ```bash curl -X GET 'http://localhost:8080/api/v1/scripts/<script-id>' ``` ### Get Script Schema / Summary ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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) ```bash 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 ```bash 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) ```bash 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 ```bash 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 ```bash # TODO: curl -X GET 'http://localhost:8080/api/v1/marketplace/scripts?category=search&page=1' ``` ### Install Script from Marketplace ```bash # 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 ```bash curl -X GET 'http://localhost:8080/api/v1/mcp/status' ``` ### List MCP Commands ```bash 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 ```bash curl -X GET 'http://localhost:8080/api/v1/prompts' ``` ### Get a Specific Prompt ```bash 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 ```bash 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 ```bash curl -X GET 'http://localhost:8080/api/v1/browser/instances' ``` ### Start a Browser Instance ```bash curl -X POST 'http://localhost:8080/api/v1/browser/instances/<id>/start' ``` ### Stop a Browser Instance ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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` ```bash # 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 | Category | Method | Endpoint | Description | |----------|--------|----------|-------------| | Health | GET | `/health` | Check service status | | LLM | GET | `/api/v1/llm-configs` | List LLM configurations | | LLM | POST | `/api/v1/llm-configs` | Add LLM configuration | | LLM | POST | `/api/v1/llm-configs/test` | Test LLM connection | | Explore | POST | `/api/v1/ai-explore/start` | Start AI exploration | | Explore | GET | `/api/v1/ai-explore/:id/stream` | Stream exploration events | | Explore | POST | `/api/v1/ai-explore/:id/stop` | Stop exploration | | Explore | POST | `/api/v1/ai-explore/:id/save` | Save generated script | | Scripts | GET | `/api/v1/scripts` | List all scripts | | Scripts | GET | `/api/v1/scripts/:id` | Get script details | | Scripts | POST | `/api/v1/scripts` | Create new script | | Scripts | PUT | `/api/v1/scripts/:id` | Update script | | Scripts | DELETE | `/api/v1/scripts/:id` | Delete script | | Scripts | GET | `/api/v1/scripts/summary` | Get scripts schema/summary | | Scripts | POST | `/api/v1/scripts/export/skill` | Export scripts as SKILL.md | | Execute | POST | `/api/v1/scripts/:id/play` | Execute a script | | Execute | GET | `/api/v1/scripts/play/result` | Get execution result data | | Execute | GET | `/api/v1/script-executions` | List execution history | | Prompts | GET | `/api/v1/prompts` | List all prompts | | Prompts | PUT | `/api/v1/prompts/:id` | Update prompt | | Browser | GET | `/api/v1/browser/instances` | List browser instances | | Cookies | GET | `/api/v1/cookies/:id` | View saved cookies | | Cookies | POST | `/api/v1/browser/cookies/save` | Save current browser cookies | | Cookies | POST | `/api/v1/browser/cookies/import` | Import cookies | | Cookies | POST | `/api/v1/browser/cookies/delete` | Delete a single cookie | | Cookies | POST | `/api/v1/browser/cookies/batch/delete` | Batch delete cookies | | MCP | GET | `/api/v1/mcp/status` | MCP server status | | MCP | GET | `/api/v1/mcp/commands` | List MCP commands | | Executor | GET | `/api/v1/executor/help` | Executor API help | | Executor | GET | `/api/v1/executor/snapshot` | Page accessibility snapshot | | Skill | GET | `/api/v1/executor/export/skill` | Export Executor skill | | Skill | GET | `/api/v1/admin/export/skill` | Export this Admin skill |