SurfAgent Browser Control — Agent Skill

Give your AI agent a real Chrome browser. Navigate, click, type, extract, and automate — all through a local REST API.

What This Is

SurfAgent runs a real Chrome browser on your desktop that your AI agent controls via a REST API (port 7201). Not headless. Not spoofed. A genuine Chrome with persistent cookies, real sessions, and a real fingerprint that passes bot detection.

Key difference from headless browsers: SurfAgent's Chrome passes hCaptcha, Cloudflare, Discord registration, and other bot detection that headless browsers fail. Your agent browses like a human.

Architecture

SurfAgent Daemon (port 7201)
  └── REST API → Chrome DevTools Protocol → Real Chrome (port 9222)

All requests go to http://localhost:7201 with Bearer auth token.

Quick Start

Check if SurfAgent is running

curl -s http://localhost:7201/health | jq .

Open a page

curl -s -X POST http://localhost:7201/browser/open \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"url": "https://github.com"}'

Get page state

curl -s -X POST http://localhost:7201/browser/state \
  -H 'Authorization: Bearer YOUR_TOKEN' | jq .

Core API Reference

Navigation

POST /browser/open — Open URL in new tab

{ "url": "https://example.com" }

Returns: { ok, tabId, title, url }

POST /browser/navigate — Navigate current tab

{ "url": "https://example.com", "tabId": "optional" }

Returns: { ok, tabId, title, url }

POST /browser/back / POST /browser/forward — History navigation

{ "tabId": "optional" }

POST /browser/reload — Reload page

{ "tabId": "optional", "ignoreCache": false }

Interaction

POST /browser/click — Click an element

{
  "selector": "#submit-btn",
  "tabId": "optional",
  "button": "left",
  "clickCount": 1
}

Also supports clicking by coordinates:

{ "x": 500, "y": 300 }

POST /browser/type — Type text (key by key)

{
  "selector": "#search-input",
  "text": "hello world",
  "tabId": "optional",
  "delay": 50
}

POST /browser/fill — Set input value directly

{
  "selector": "#email",
  "value": "user@example.com",
  "tabId": "optional"
}

React/Vue form fields: Use /browser/fill with dispatchEvents: true. Direct .value = assignment won't trigger React's state updates.

POST /browser/select — Select dropdown option

{
  "selector": "#country",
  "value": "US",
  "tabId": "optional"
}

POST /browser/hover — Hover over element

{ "selector": ".menu-trigger", "tabId": "optional" }

POST /browser/scroll — Scroll the page

{
  "tabId": "optional",
  "direction": "down",
  "amount": 500,
  "selector": "optional-scroll-container"
}

Direction: up, down, left, right

POST /browser/press — Press a keyboard key

{
  "key": "Enter",
  "tabId": "optional",
  "modifiers": ["Shift"]
}

Common keys: Enter, Tab, Escape, ArrowDown, Backspace, Delete

Page State & Content

POST /browser/state — Full structured page state

{
  "tabId": "optional",
  "includeElements": true,
  "maxElements": 100
}

Returns:

• Page type (login, dashboard, feed, checkout, etc.)
• Auth state (logged_in, logged_out, session_expired)
• Interactive elements with selectors, roles, visibility, text
• Form state (fields, filled count, submit button)
• Blockers (cookie banners, captchas, auth walls)
• Modals with actions
• Content regions (nav, main, sidebar, footer)

POST /browser/extract — Extract text content

{
  "tabId": "optional",
  "selector": "optional — defaults to body",
  "format": "text"
}

Format: text, html, markdown

POST /browser/screenshot — Capture screenshot

{
  "tabId": "optional",
  "format": "png",
  "fullPage": false,
  "quality": 80,
  "clip": { "x": 0, "y": 0, "width": 800, "height": 600 }
}

Returns: { ok, data } (base64-encoded image)

POST /browser/evaluate — Run JavaScript

{
  "tabId": "optional",
  "expression": "document.title"
}

Returns: { ok, result }

⚠️ Use evaluate as a last resort. Prefer structured API calls over raw JS.

Tab Management

GET /browser/tabs — List all open tabs

Returns: [{ id, url, title, active }]

POST /browser/tab/activate — Switch to a tab

{ "tabId": "TARGET_TAB_ID" }

POST /browser/tab/close — Close a tab

{ "tabId": "TARGET_TAB_ID" }

POST /browser/tab/name — Bookmark a tab by name

{ "tabId": "TARGET_TAB_ID", "name": "twitter" }

Then use "tabId": "name:twitter" in any request to target it.

Important: Close tabs when done, especially social media tabs (X/Twitter). Open tabs flood CDP with events and degrade performance.

Blocker Resolution

POST /browser/resolve-blocker — Auto-dismiss blockers

{ "tabId": "optional" }

Handles: cookie consent banners, newsletter popups, notification permission dialogs. Returns: { ok, resolved, blockerType }

POST /browser/captcha/detect — Check for CAPTCHAs

{ "tabId": "optional" }

POST /browser/captcha/solve — Attempt CAPTCHA solve

{ "tabId": "optional" }

Forms

POST /browser/fill-form — Fill multiple form fields at once

{
  "tabId": "optional",
  "fields": [
    { "selector": "#email", "value": "user@example.com" },
    { "selector": "#password", "value": "secret123" },
    { "selector": "#remember", "checked": true }
  ],
  "submit": false
}

File Operations

POST /browser/upload — Upload a file to a file input

{
  "selector": "input[type=file]",
  "filePath": "/path/to/document.pdf",
  "tabId": "optional"
}

POST /browser/download — Download current page or resource

{
  "url": "https://example.com/report.pdf",
  "savePath": "/path/to/save/"
}

Browser Lifecycle

POST /browser/launch — Start the managed browser

{ "headless": false }

POST /browser/close — Close the managed browser

Closes all tabs and shuts down Chrome.

GET /health — Daemon health check

Returns: { status, version, browser, uptime }

GET /status — Detailed status

Returns: { daemon, browser, gateway, system }

Auth

All requests (except /health, /status, /readiness) require:

Authorization: Bearer <token>

The daemon generates a token on first start and saves it to ~/.surfagent/daemon-token.txt.

Common Patterns

Login to a Site

1. navigate to login page
2. state → confirm it's a login page
3. fill email + password fields
4. click submit
5. state → confirm auth_state changed to logged_in

Scrape Data from a Table

1. navigate to page
2. state → find table elements
3. evaluate → extract table rows as JSON
4. scroll down if needed
5. repeat extraction

Fill a Multi-Step Form

1. state → identify form fields + which step
2. fill-form with current step's fields
3. click "Next" / submit
4. state → confirm we're on next step
5. repeat until done

Monitor a Value

1. navigate to page
2. evaluate → extract the value
3. wait N seconds
4. evaluate again → compare

Tips & Gotchas

Close tabs when done. Open tabs (especially X/Twitter) generate constant CDP events that slow everything down. Close them after you're finished.

Use fill not type for form fields. type simulates keystrokes (slow, can trigger autocomplete). fill sets the value directly. Use type only when you need to trigger keystroke-based UI (search suggestions, autocomplete dropdowns).

React/Vue forms need event dispatch. If fill doesn't trigger the framework's state, add dispatchEvents: true. This dispatches input, change, and blur events that React/Vue listen for.

Check for blockers first. Many sites show cookie banners or modals on first visit. Call state → check for blockers → resolve-blocker before trying to interact.

State tokens from /browser/state expire. The daemon keeps a ring buffer of 5 state snapshots per tab. If you wait too long between state calls, old tokens may be evicted.

Evaluate is powerful but fragile. Raw JS can break on page updates. Prefer state + click/fill for interactions, and reserve evaluate for data extraction.

MCP Tools (via surfagent-mcp)

If using through the MCP server rather than direct HTTP:

For perception tools (perceive, annotate, scene_diff), see the surfagent-perception skill.