itsobaa/chrome-sandbox repository overview

⁠chrome-sandbox

Provider-neutral cloud Chrome runtime for AI agents and browser automation tools.

Supports:

• Chrome DevTools Protocol (CDP) for Puppeteer, Playwright, Browser Use, and similar tools
• WebDriver endpoint for Selenium-compatible clients
• Built-in MCP server endpoint (/) for Streamable HTTP clients
• noVNC desktop for visual debugging
• Optional bring-your-own proxy (including Webshare and other providers)
• Runtime proxy rotation through a token-protected admin API
• Token gate in front of all exposed services

⁠Quick start

Build:

docker build -t chrome-sandbox:local .

Run:

docker run --rm -it \
  -p 6080:6080 \
  -p 5900:5900 \
  -p 9222:9222 \
  -p 9515:9515 \
  -p 5800:5800 \
  -p 5901:5901 \
  -e AUTH_TOKEN="change-me" \
  chrome-sandbox:local

Open noVNC at (token required):

• http://127.0.0.1:6080/vnc.html?token=change-me

⁠Docker Compose

Use the included compose file:

docker compose up --build -d

File:

• docker-compose.yml

By default it exposes:

• 6080 noVNC (token-gated)
• 9222 CDP (token-gated)
• 9515 WebDriver (token-gated)
• 5800 Admin API (token-gated)
• 5901 MCP Streamable HTTP (token-gated)

Set a strong value for AUTH_TOKEN in docker-compose.yml before production usage.

⁠Persistence model

• Browser profile/data path: /home/chrome/.config/chromium
• Runtime state path: /state (token and proxy state)

To prevent data loss, persist both /home/chrome and /state. The included compose and Kubernetes examples are wired for this.

⁠Lifecycle hooks (optional)

You can run custom scripts during container lifecycle to support external orchestration systems (for example Grabba-style self-registration).

Hook env vars:

• PRE_START_HOOK - runs once before supervisor starts services
• POST_START_HOOK - runs once after Chrome becomes healthy
• PRE_STOP_HOOK - runs once when container receives shutdown signal
• POST_STOP_HOOK - runs after PRE_STOP_HOOK
• HOOK_TIMEOUT_SECONDS - per-hook timeout (default 30)
• HOOK_REQUIRED - if true, startup fails when pre/post start hook fails (default false)
• CHROME_READY_TIMEOUT_SECONDS - max wait for Chrome health before POST_START_HOOK (default 60)

Behavior:

• Hooks are opt-in (unset hook path => skipped).
• Hook paths must exist and be executable inside container.
• Hook failures are logged; only required startup hooks can fail container startup.
• Hooks run with container env vars available (AUTH_TOKEN, endpoint ports, etc.).

Example compose snippet:

environment:
  PRE_START_HOOK: "/hooks/pre-start.sh"
  POST_START_HOOK: "/hooks/post-start.sh"
  PRE_STOP_HOOK: "/hooks/pre-stop.sh"
  POST_STOP_HOOK: "/hooks/post-stop.sh"
  HOOK_TIMEOUT_SECONDS: "30"
  HOOK_REQUIRED: "false"
volumes:
  - ./hooks:/hooks:ro

Grabba mapping:

• registration/update flow -> POST_START_HOOK
• offline/deregister flow -> PRE_STOP_HOOK
• optional final cleanup -> POST_STOP_HOOK

⁠Kubernetes (simple manifest)

Apply:

kubectl apply -f k8s/chrome-sandbox.yaml

Manifest includes:

• namespace
• secret (AUTH_TOKEN)
• deployment
• cluster-internal service
• PVC-backed persistent storage for /home/chrome and /state

To expose externally, add your ingress or switch the service type (for example LoadBalancer) based on your cluster setup. Set PVC storage class names in the manifest if your cluster requires explicit storage class selection.

⁠Token-gated endpoints

• noVNC: http://<host>:6080
• CDP: http://<host>:9222
• WebDriver: http://<host>:9515
• Admin API: http://<host>:5800
• MCP: http://<host>:5901/

⁠Chrome sandbox mode

• Default launch uses Chromium sandbox mode.
• Image includes chromium-sandbox to support sandboxed launches in hardened environments.
• If sandbox startup fails at runtime, launcher retries once with --no-sandbox so service still comes up.
• Set CHROME_NO_SANDBOX=true only when your container runtime requires it.
• CHROME_NO_SANDBOX=true can show Chrome's "unsupported command line flag --no-sandbox" warning banner.

⁠Admin landing page public URL overrides

When admin, noVNC, and MCP are exposed on different hosts, set these env vars so the admin landing page generates correct links and MCP config snippets:

• PUBLIC_ADMIN_BASE_URL (optional; default uses current admin page origin)
• PUBLIC_VNC_BASE_URL (default http://localhost:6080)
• PUBLIC_MCP_BASE_URL (default http://localhost:5901)

⁠Using with MCP clients (Cursor, Claude, others)

This image now includes a built-in MCP server. Use Streamable HTTP against http://<host>:5901 with the same token auth used elsewhere.

⁠1) MCP initialize (Streamable HTTP)

curl -sS http://127.0.0.1:5901 \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"demo","version":"1.0.0"}}
  }'

⁠2) List tools

curl -sS http://127.0.0.1:5901 \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

⁠3) Example tool call

Open URL:

curl -sS http://127.0.0.1:5901 \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{"name":"open_url","arguments":{"url":"https://example.com"}}
  }'

⁠3b) Form interaction example (fill + submit + read result)

# 1) Navigate
curl -sS http://127.0.0.1:5901 \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"open_url","arguments":{"url":"https://example.com/form"}}}'

# 2) Type into an input
curl -sS http://127.0.0.1:5901 \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"type","arguments":{"selector":"input[name=\"email\"]","text":"[email protected]"}}}'

# 3) Click submit
curl -sS http://127.0.0.1:5901 \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"click","arguments":{"selector":"button[type=\"submit\"]"}}}'

# 4) Wait for success UI then extract text
curl -sS http://127.0.0.1:5901 \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"wait_for_selector","arguments":{"selector":".success-message","visible":true,"timeoutMs":15000}}}'

curl -sS http://127.0.0.1:5901 \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"extract_text","arguments":{"selector":".success-message"}}}'

⁠4) Cursor MCP config template

Configure Cursor to call this server over HTTP:

{
  "mcpServers": {
    "cloudChrome": {
      "transport": {
        "type": "streamable_http",
        "url": "http://127.0.0.1:5901",
        "headers": {
          "Authorization": "Bearer change-me"
        }
      }
    }
  }
}

⁠5) Claude Desktop MCP template

Point Claude to the same Streamable HTTP endpoint:

{
  "mcpServers": {
    "cloudChrome": {
      "transport": {
        "type": "streamable_http",
        "url": "http://127.0.0.1:5901",
        "headers": {
          "Authorization": "Bearer change-me"
        }
      }
    }
  }
}

⁠6) Non-MCP direct clients (Puppeteer/Playwright/Selenium)

You can also connect tools directly:

• Puppeteer/Playwright: CDP via http://<host>:9222 with token header
• Selenium: WebDriver via http://<host>:9515 with token header

For direct CDP clients that cannot set headers, use token query param where supported by your client path.

⁠Authentication

All exposed endpoints are token-gated.

Use either:

• Authorization: Bearer <AUTH_TOKEN>
• X-Auth-Token: <AUTH_TOKEN>
• ?token=<AUTH_TOKEN> (recommended for browser noVNC access)

If AUTH_TOKEN is not provided, one is generated at startup and saved to /state/auth_token in the container.

If /state/auth_token already exists and AUTH_TOKEN env is unset, startup reuses that persisted token.

That means endpoints still require a token; clients just need to read the generated one from /state/auth_token if you did not set AUTH_TOKEN explicitly.

⁠Optional proxy (BYO)

No proxy is required. By default, Chrome uses direct egress.

Startup proxy configuration:

• PROXY_URL (example: http://username:[email protected]:8080)
• PROXY_BYPASS (optional Chrome bypass list)

This works with Webshare and any provider that exposes a standard HTTP/HTTPS proxy endpoint.

⁠Rotate proxy at runtime

Set or update proxy:

curl -X POST http://127.0.0.1:5800/proxy \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"proxyUrl":"http://user:[email protected]:8080","bypassList":"localhost,127.0.0.1"}'

Disable proxy:

curl -X DELETE http://127.0.0.1:5800/proxy \
  -H "Authorization: Bearer change-me"

Read proxy state:

curl http://127.0.0.1:5800/proxy \
  -H "Authorization: Bearer change-me"

⁠Admin API

• GET /health (token required)
• GET / (public landing page with token helper UI, route links, and MCP config snippet)
• GET /session (token required)
• GET /proxy (token required)
• POST /proxy (token required)
• DELETE /proxy (token required)

GET /session is for orchestration state discovery and currently includes:

• public endpoint metadata
• Chrome runtime health and active target count
• proxy mode/source
• persistence hints for profile/state paths

⁠Built-in MCP tools (v1)

• session_info
• list_tabs
• new_tab
• switch_tab
• close_tab
• open_url
• get_html
• click
• type
• wait_for_selector
• wait_for_navigation
• extract_text
• evaluate_js
• screenshot
• get_proxy
• set_proxy
• clear_proxy

⁠Security notes

• Use strong random AUTH_TOKEN values.
• Use VNC_PASSWORD to protect VNC access.
• In production, place exposed ports behind TLS and access controls.