Skip to content
▚ AgentBrowser
Star on GitHub
▚ Quickstart

From clone to first agent task.

Five steps. One local binary, one dev key. Everything below runs against a self-hosted instance on localhost:8080 with the built-in key bdab-dev-key.

View the repo RUNNING.md →
Step 1 · Run

Run it in 60 seconds.

Go toolchain required. Clone, build the server binary, and start it. It listens on :8080 by default — set PORT if that port is taken.

agent-browser — build & run
# clone and build
git clone https://github.com/ByteDeskAI/bytedesk-agent-browser
cd bytedesk-agent-browser
go build ./cmd/server && ./server
 
# → listening on :8080
# port taken? PORT=9000 ./server
Step 2 · Session

Create a session.

A session is a warm cloud browser claimed from the pool. Authenticate with the anchor-api-key header; the response is an Anchor-shaped {data:{…}} envelope.

Request
curl -s http://localhost:8080/v1/sessions \
  -H "anchor-api-key: bdab-dev-key" \
  -H "content-type: application/json" \
  -d '{"browser":{"headless":{"active":true}}}'
Response
{ "data": {
    "id": "0f5a2b6e…",
    "cdp_url": "ws://…/?apiKey=…&sessionId=…",
    "live_view_url": "https://…"
} }
Step 3 · Drive

Drive it with Playwright.

Point unmodified chromium.connectOverCDP at the returned cdp_url. Puppeteer works the same way. No SDK, no patched client.

import { chromium } from 'playwright';

const { data } = await (await fetch(
  'http://localhost:8080/v1/sessions',
  { method: 'POST',
    headers: { 'anchor-api-key': 'bdab-dev-key' } }
)).json();

const browser = await chromium.connectOverCDP(data.cdp_url);  // ← drop-in
const page = browser.contexts()[0].pages()[0];
await page.goto('https://example.com');
console.log(await page.title());

Prefer a runnable version? ./demo/run_demo.sh spins up a session and drives it end-to-end against a running server.

Step 4 · Agent

Run an AI task.

Hand the browser a goal. With async: true the call returns immediately with a lowercase running status and a workflow id; poll /status for the UPPERCASE lifecycle — RUNNING → COMPLETED. Watch each step live over /ws.

Start the task
curl -s http://localhost:8080/v1/tools/perform-web-task \
  -H "anchor-api-key: bdab-dev-key" \
  -H "content-type: application/json" \
  -d '{
    "prompt": "find the top post on Hacker News",
    "provider": "claude",
    "async": true
  }'

→ { "data": { "id": "wf_1a2b…", "status": "running" } }
Poll to completion
curl -s \
  http://localhost:8080/v1/tools/perform-web-task/wf_1a2b…/status \
  -H "anchor-api-key: bdab-dev-key"

→ { "data": { "status": "RUNNING" } }
→ { "data": { "status": "COMPLETED",
      "result": { "title": "…" } } }

Providers need a credential: a provider API key, OAuth, or ACP — drive an already-logged-in agent CLI, no raw key required. Set one before you call perform-web-task.

Step 5 · MCP

Wire up MCP.

Expose the browser as tools to any MCP client. Point command at the bdab-mcp binary and set BDAB_BASE to your server. The client gets browser_navigate, snapshot, click, type, and screenshot, each backed by a live session.

{
  "mcpServers": {
    "bdab": {
      "command": "/path/to/bdab-mcp",
      "env": { "BDAB_BASE": "http://localhost:8080" }
    }
  }
}

Want to see it do real work? The demo/advanced walkthrough points Claude at these tools to compile a lead list off live pages.

Next steps

Where to go from here.

Ship your first agent task

Open-source and free to self-host. Managed cloud is coming.

Star on GitHub Join the Cloud waitlist Quickstart →