sendblue-browser-use

A standalone debug browser for agents. Stealth-patched Chromium behind a tiny HTTP API, with persistent named sessions, an easy purge endpoint, configurable auto screenshots, and CDP attach so any client (Playwright, Puppeteer, undetected-chromedriver, custom scripts) can drive it.

It runs as its own process — not tied to any one Claude / Cursor / Codex session — so multiple agents can share it concurrently, debug each other's flows, and reuse a logged-in session without paying the auth tax every run.

Why this exists

Quick start (local)

Prereqs: Bun >=1.3 and Node.js >=20 on your PATH.

git clone https://github.com/sendblue-api/sendblue-browser-use.git
cd sendblue-browser-use
bun install
bun --bun x patchright install chromium

cp .env.example .env
# generate and set the required token
TOKEN="$(openssl rand -hex 32)"
sed -i.bak "s/^BROWSER_USE_API_KEY=.*/BROWSER_USE_API_KEY=$TOKEN/" .env
rm .env.bak

bun run dev

Then in another terminal:

source .env
TOKEN="Authorization: Bearer $BROWSER_USE_API_KEY"

# 1. create a persistent session (log in here once, reuse it forever)
curl -s -X POST http://127.0.0.1:8787/sessions \
  -H "$TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"qa","persistent":true}'

# 2. navigate
curl -s -X POST http://127.0.0.1:8787/sessions/qa/navigate \
  -H "$TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://trybloom.so/"}'

# 3. screenshot
curl -s http://127.0.0.1:8787/sessions/qa/screenshot?fullPage=true \
  -H "$TOKEN" -o /tmp/qa.png

# 4. wipe state without losing the session
curl -s -X POST http://127.0.0.1:8787/sessions/qa/purge -H "$TOKEN"

Quick start (Docker)

echo "BROWSER_USE_API_KEY=$(openssl rand -hex 32)" > .env
docker compose up -d

Same API, exposed on 127.0.0.1:8787. Data persists in ./data/. CDP stays loopback-only inside the container by default; to attach CDP from the host, uncomment CDP_BIND and the 127.0.0.1:9222:9222 port mapping in docker-compose.yml on a trusted machine only.

Install into your agent

The repo ships three packaging layers so any agent can drive the daemon with one line of config.

MCP (Claude Desktop, Codex, Cursor, Antigravity, Cline, Windsurf)

The cross-agent path. Wraps the HTTP API as MCP tools (health, create_session, navigate, screenshot, script, get_cdp_url, purge_session, etc).

{
  "mcpServers": {
    "sendblue-browser": {
      "command": "npx",
      "args": ["-y", "sendblue-browser-mcp@0.2.3"],
      "env": {
        "BROWSER_USE_URL": "http://127.0.0.1:8787",
        "BROWSER_USE_API_KEY": "<same token you start the daemon with>"
      }
    }
  }
}

Drop into ~/.cursor/mcp.json, ~/Library/Application Support/Claude/claude_desktop_config.json, ~/.gemini/config/mcp_config.json, etc. For Codex:

codex mcp add sendblue-browser \
  --env BROWSER_USE_URL=http://127.0.0.1:8787 \
  --env BROWSER_USE_API_KEY=<daemon-token> \
  -- npx -y sendblue-browser-mcp@0.2.3

Wrapper source: mcp/.

Claude Code plugin

/plugin install sendblue-api/sendblue-browser-use

Pulls .claude-plugin/plugin.json + skills/sendblue-browser/SKILL.md from this repo.

Codex / Antigravity / Cline skill

The same skills/sendblue-browser/SKILL.md works as a skill across Codex, Google Antigravity, and Cline. Copy the folder into:

AGENTS.md repos

If your repo already follows the agents.md convention, the AGENTS.md in this repo doubles as a copy-pasteable section for any consumer repo that wants to call this daemon.

API

All routes require Authorization: Bearer $BROWSER_USE_API_KEY except /health.

POST /sessions/:name/script passes code directly to Playwright's page.evaluate. Send a JavaScript expression, or wrap statements in an IIFE. Scripts time out after 30s by default; pass timeoutMs up to 120000, or 0 to disable the request timeout.

{ "code": "(() => { const x = 1; return x; })()" }

Errors

All non-2xx responses share the same envelope. Failures from Playwright are truncated to one line before being returned; the full message is logged server-side with proxy credentials redacted.

{ "error": { "code": "navigate_failed", "message": "net::ERR_NAME_NOT_RESOLVED" } }

Session options

{
  name: string;            // required, [a-z0-9_-]
  persistent?: boolean;    // default true — profile data survives restarts
  headless?: boolean | "new"; // persistent sessions only; non-persistent uses DEFAULT_HEADLESS
  viewport?: { width, height };
  userAgent?: string;
  locale?: string;         // default "en-US"
  timezone?: string;
  traces?: boolean;        // capture a Playwright trace.zip on session close
  proxy?: { server, username?, password?, bypass? };
}

Cookie shape

POST /sessions/:name/cookies accepts up to 500 Playwright-style cookies:

{
  cookies: Array<{
    name: string;
    value: string;
    url?: string;       // absolute URL, or domain + path
    domain?: string;
    path?: string;
    expires?: number;
    httpOnly?: boolean;
    secure?: boolean;
    sameSite?: "Strict" | "Lax" | "None";
  }>;
}

Each cookie must include either url or both domain and path.

Persistent vs non-persistent

• persistent: true (default) — cookies, localStorage, IndexedDB persist under ~/.sendblue-browser-use/profiles/<name>/. After a daemon restart, recreate the same named persistent session to reuse that profile. CDP attach is not available for these sessions because each gets its own private browser instance.
• persistent: false — shares the central Chromium process via a fresh BrowserContext. State is in-memory only. CDP attach IS available via /sessions/:name/cdp-url, which returns the shared browser-level CDP endpoint plus a targetId for the session page. CDP clients can see the shared debug browser, so keep the CDP port local and trusted and select the returned target before driving.

Pick persistent for "log in once, debug for a week" workflows. Pick non-persistent when you need to attach Playwright / Puppeteer directly.

Examples