chrome-use/docs/src/app/cdp-mode/page.mdx

import { pageMetadata } from "@/lib/page-metadata"

export const metadata = pageMetadata("cdp-mode")

# CDP Mode

Connect to an existing browser via Chrome DevTools Protocol:

Default behavior in this fork: when `--cdp` is omitted, agent-browser requires an existing browser at `localhost:9333`. If CDP is unavailable, the command fails fast (no local-launch fallback).

Project policy:

- `--profile` / `AGENT_BROWSER_PROFILE` are forbidden
- `--channel` / `AGENT_BROWSER_CHANNEL` are forbidden

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

1. Reading Chrome's `DevToolsActivePort` file from the default user data directory
2. Falling back to probing common debugging ports (9222, 9229, 9333)

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

Playwright overrides the browser's color scheme to `light` by default when connecting via CDP. Use `--color-scheme` to set a persistent preference:

```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
```

## Stealth behavior

`--stealth` is enabled by default across connection modes, but capabilities depend on how you connect:

<table>
  <thead>
    <tr><th>Connection type</th><th>Stealth capabilities</th></tr>
  </thead>
  <tbody>
    <tr><td>Local launch</td><td>Chromium launch args + context init scripts</td></tr>
    <tr><td>CDP / auto-connect</td><td>Context init scripts</td></tr>
    <tr><td>Cloud providers</td><td>Context init scripts (Kernel may also apply provider-managed stealth)</td></tr>
  </tbody>
</table>

Use `--debug` to print the active connection type and applied stealth capabilities.

## 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 &lt;name&gt;</code></td><td>Use isolated session</td></tr>
    <tr><td><code>-p &lt;provider&gt;</code></td><td>Cloud browser provider (<code>browserbase</code>, <code>browseruse</code>, <code>kernel</code>)</td></tr>
    <tr><td><code>--headers &lt;json&gt;</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 &lt;args&gt;</code></td><td>Browser launch args (comma-separated)</td></tr>
    <tr><td><code>--user-agent &lt;ua&gt;</code></td><td>Custom User-Agent string</td></tr>
    <tr><td><code>--proxy &lt;url&gt;</code></td><td>Proxy server URL</td></tr>
    <tr><td><code>--proxy-bypass &lt;hosts&gt;</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>--full, -f</code></td><td>Full page screenshot</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 &lt;scheme&gt;</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 cloud browser infrastructure when local browsers aren't available:

```bash
# Browserbase
export BROWSERBASE_API_KEY="your-api-key"
export BROWSERBASE_PROJECT_ID="your-project-id"
agent-browser -p browserbase open https://example.com

# Browser Use
export BROWSER_USE_API_KEY="your-api-key"
agent-browser -p browseruse open https://example.com

# Kernel
export KERNEL_API_KEY="your-api-key"
agent-browser -p kernel open https://example.com

# Or via environment variable
export AGENT_BROWSER_PROVIDER=browserbase
agent-browser open https://example.com
```

The `-p` flag takes precedence over `AGENT_BROWSER_PROVIDER`.