CDP Mode

Connect to an existing browser via Chrome DevTools Protocol:

bash

# 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:

bash

# 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:

bash

# 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:

bash

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:

bash

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

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

Cloud providers

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

bash

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.