Documentation

AI agent integration guide — managed sessions, fingerprint profiles, and residential/datacenter proxy routing over standard CDP.

Quick Start

Select your AI agent below. The install script configures Clawbrowser and wires it into your agent automatically.

Paste this prompt into Claude Code or Claude Desktop to install automatically.

Install prompt
Install Clawbrowser and clawctl by following the official Clawbrowser install documentation.

Primary docs:
- https://raw.githubusercontent.com/clawbrowser/clawbrowser/main/INSTALL.md
- https://github.com/clawbrowser/clawbrowser

Instructions:
1. Read INSTALL.md first.
2. Follow the documented installation flow exactly.
3. Start from the standalone clawctl archive for the current OS/arch.
4. Do not download the browser archive manually as the bootstrap path.
5. Do not download the portable runtime manually unless INSTALL.md explicitly documents that as an offline/pre-extracted runtime path.
6. Do not use npm, npx, curl-piped installers, or a raw source checkout as the install path.
7. Run clawctl install so it can install or reuse Clawbrowser and install the portable runtime when needed.
8. Use the documented target/integration selection from INSTALL.md.
9. After installation, verify the browser using the verification steps documented in INSTALL.md.

API key:
- First check ${XDG_CONFIG_HOME:-$HOME/.config}/clawbrowser/config.json.
- If api_key already exists, do not ask again.
- If api_key is missing, ask once for the real API key from https://app.clawbrowser.ai.
- Save it using the documented clawctl config command.
- Never store the API key in shell rc files, environment variables, MCP config, agent config, project files, or logs.

Expected result:
- Standalone clawctl is installed and available.
- clawctl install has completed successfully.
- Clawbrowser is installed or reused.
- The portable Linux runtime is installed only when the host requires it.
- The selected agent integration is configured according to INSTALL.md.
- clawctl start works.
- Browser verification passes according to INSTALL.md.
Get API key → app.clawbrowser.ai

Manual Quick Start

Pre-built prompt

Use this prompt to get started faster

Drop this into any AI agent (Claude, GPT-4, Gemini, etc.) to have it automatically install and deploy Clawbrowser. Fill in the [BRACKETED] placeholders before sending — or let the agent ask you for them.

Or set the API key and start a session directly from the terminal. Use fingerprint flags after -- when identity matters.

export CLAWBROWSER_API_KEY=clawbrowser_xxxxx

# Start a managed browser session
clawbrowser start --session work -- https://example.com

# Print the local CDP endpoint for your agent
clawbrowser endpoint --session work

# Or start a fingerprint-backed session when identity matters
clawbrowser start --session identity -- --fingerprint=fp_work --country=US https://example.com

Agent Integration

Connect your automation framework to the CDP endpoint the same way you would with any Chromium build. Fingerprint spoofing and residential/datacenter proxy routing are transparent to your agent, reducing CAPTCHA and anti-bot interruptions caused by mismatched browser identity signals.

Playwright (Python)

from playwright.async_api import async_playwright

async with async_playwright() as p:
    endpoint = "http://127.0.0.1:9222"  # from: clawbrowser endpoint --session work
    browser = await p.chromium.connect_over_cdp(endpoint)
    page = browser.contexts[0].pages[0]
    await page.goto("https://example.com")
    content = await page.content()

Playwright (Node.js)

const { chromium } = require('playwright');

const endpoint = 'http://127.0.0.1:9222'; // from: clawbrowser endpoint --session work
const browser = await chromium.connectOverCDP(endpoint);
const page = browser.contexts()[0].pages()[0];
await page.goto('https://example.com');

Puppeteer

const puppeteer = require('puppeteer');

const endpoint = 'http://127.0.0.1:9222'; // from: clawbrowser endpoint --session work
const browser = await puppeteer.connect({ browserURL: endpoint });
const [page] = await browser.pages();
await page.goto('https://example.com');

CLI Reference

# Start or reattach to a managed browser session
clawbrowser start --session work -- https://example.com

# Print the CDP endpoint
clawbrowser endpoint --session work

# Show session status
clawbrowser status --session work

# Restart the managed session with --regenerate
clawbrowser rotate --session work

# Stop the session
clawbrowser stop --session work

# List cached browser profiles
clawbrowser list --session work

# Choose a CDP port
clawbrowser start --session work --port 9222 -- https://example.com

# Pass browser-level fingerprint, proxy type, and geo flags
clawbrowser start --session us -- --fingerprint=fp_us --country=US --connection-type=residential
clawbrowser start --session dc -- --fingerprint=fp_dc --country=US --connection-type=datacenter

# Keep the internal verification page enabled
clawbrowser start --session work --verify -- https://example.com

Launcher Output

Endpoint and status

start prints the local HTTP CDP endpoint after readiness checks pass. Use status or endpoint when an agent needs to reconnect later.

$ clawbrowser start --session work -- https://example.com
http://127.0.0.1:9222

$ clawbrowser status --session work
session=work status=running endpoint=http://127.0.0.1:9222 backend=app

Profile list

list asks the browser to print cached fingerprint profiles as JSON. It is not a streaming readiness event feed.

$ clawbrowser list --session work
[
   {
      "id": "fp_work",
      "created_at": "2026-04-27T10:00:00Z",
      "country": "US"
   }
]

Browser logs

Browser and container logs are still useful for debugging startup failures, but agents should use the endpoint and status commands for normal readiness detection.

Multi-Profile Management

Each named session has its own tracked CDP endpoint. Run multiple sessions simultaneously by giving each one a different session name and port. For identity separation, use distinct fingerprint IDs.

clawbrowser start --session agent-us --port 9222 -- https://example.com
clawbrowser start --session agent-de --port 9223 -- https://example.com
clawbrowser start --session agent-uk --port 9224 -- https://example.com

Tips for AI Agents

  • Reuse sessions and profile IDs for continuity. When using fingerprint mode, the same fingerprint ID reuses its cached profile data.
  • Use clawbrowser endpoint --session <name> to reconnect to a running session.
  • The launcher skips the verification page by default for faster startup. Pass --verify when you need to inspect it.
  • One proxy per session — for residential/datacenter proxy-backed profiles, the proxy does not rotate mid-session.
  • Clawbrowser reduces CAPTCHA and anti-bot challenges caused by inconsistent browser/proxy identity signals, but it should not be described as a universal CAPTCHA bypass.
  • Don't override fingerprint properties via CDP — Clawbrowser handles fingerprint overrides at the engine level. CDP-level overrides may conflict and create detectable inconsistencies.
  • Use descriptive session names like agent-us or de-scraper-main for easier management.

Error Handling

The launcher exits non-zero on startup failures. Check the exit code and the error line to decide whether to retry, restart the session, or alert a human. For fingerprint sessions, rotate passes--regenerate to the browser.

[clawbrowser] ERROR: API key cannot be empty.
[clawbrowser] ERROR: Timed out waiting for CDP on port 9222
[clawbrowser] error: invalid API key
[clawbrowser] error: cannot reach API at https://api.clawbrowser.ai
← Back to home