CDP Mode

Connect to an existing browser via Chrome DevTools Protocol:

# Start Chrome with: google-chrome --remote-debugging-port=9222

# Connect once, then run commands without --cdp
agent-browser connect 9222
agent-browser snapshot
agent-browser tab
agent-browser close

# Or pass --cdp on each command
agent-browser --cdp 9222 snapshot

Remote WebSocket URLs

Connect to remote browser services via WebSocket URL:

# Connect to remote browser service
agent-browser --cdp "wss://browser-service.com/cdp?token=..." snapshot

# Works with any CDP-compatible service
agent-browser --cdp "ws://localhost:9222/devtools/browser/abc123" open example.com

The --cdp flag accepts either:

A port number (e.g., 9222) for local connections via http://localhost:{port}
A full WebSocket URL (e.g., wss://... or ws://...) for remote browser services

Auto-Connect

Use --auto-connect to automatically discover and connect to a running Chrome instance without specifying a port:

# Auto-discover running Chrome with remote debugging
agent-browser --auto-connect open example.com
agent-browser --auto-connect snapshot

# Or via environment variable
AGENT_BROWSER_AUTO_CONNECT=1 agent-browser snapshot

Auto-connect discovers Chrome by:

Reading Chrome's DevToolsActivePort file from the default user data directory
Falling back to probing common debugging ports (9222, 9229)
If HTTP-based discovery (/json/version, /json/list) fails, falling back to a direct WebSocket connection

This is useful when:

Chrome 144+ has remote debugging enabled via chrome://inspect/#remote-debugging (which uses a dynamic port)
You want a zero-configuration connection to your existing browser
You don't want to track which port Chrome is using

Color scheme

Use --color-scheme to set a persistent preference when connecting via CDP:

agent-browser --cdp 9222 --color-scheme dark open https://example.com
agent-browser --cdp 9222 snapshot  # stays in dark mode

Or set it globally via config or environment variable:

AGENT_BROWSER_COLOR_SCHEME=dark agent-browser --cdp 9222 open https://example.com

Use cases

This enables control of:

Electron apps
Chrome/Chromium with remote debugging
WebView2 applications
Remote browser services (via WebSocket URL)
Any browser exposing a CDP endpoint

Global options

Option	Description
`--session <name>`	Use isolated session
`--profile <path>`	Persistent browser profile directory
`-p <provider>`	Cloud browser provider (`browserbase`, `browseruse`, `kernel`, `browserless`)
`--headers <json>`	HTTP headers scoped to origin
`--executable-path`	Custom browser executable
`--args <args>`	Browser launch args (comma-separated)
`--user-agent <ua>`	Custom User-Agent string
`--proxy <url>`	Proxy server URL
`--proxy-bypass <hosts>`	Hosts to bypass proxy
`--json`	JSON output for scripts
`--name, -n`	Locator name filter
`--exact`	Exact text match
`--headed`	Show browser window
`--cdp <port\|url>`	CDP connection (port or WebSocket URL)
`--auto-connect`	Auto-discover and connect to running Chrome
`--color-scheme <scheme>`	Persistent color scheme (`dark`, `light`, `no-preference`)
`--debug`	Debug output

Cloud providers

Use the -p flag to connect to a cloud browser provider instead of launching a local browser:

agent-browser -p browserbase open https://example.com

See the Providers section for setup and configuration of each supported provider: Browser Use, Browserbase, Browserless, and Kernel.