browserwing-admin

What this skill does

# 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-compatibl