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 targets the managed automation browser on `localhost:9333`. If `:9333` is unavailable, it auto-starts Chrome with the persistent profile `~/.agent-browser/chrome-bot-profile` and retries the CDP connection.

If you want to pre-start that managed browser explicitly, run:

```bash
agent-browser start
abs start
```

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

Use this mode only when you intentionally want to attach to an existing manual browser session. Recent Chrome builds may display a permission prompt before allowing remote debugging access to that session.

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