Chris Tate
12d79e4428
Fixes #519. Playwright defaults `colorScheme` to `light` on all new contexts, overriding the browser/OS dark mode setting. This is especially disruptive in CDP mode, where every reconnection resets the scheme. The `set media dark` command also didn't persist its choice to new tabs or pages. - Add `--color-scheme <dark|light|no-preference>` flag, config key (`colorScheme`), and env var (`AGENT_BROWSER_COLOR_SCHEME`) - Store the preference in `BrowserManager` and automatically apply it to all new contexts (via Playwright's context option) and all new pages (via `page.emulateMedia` in `setupPageTracking`) - `set media dark/light` now also persists its choice for subsequent pages and tabs
140 lines
4.8 KiB
Plaintext
140 lines
4.8 KiB
Plaintext
import { pageMetadata } from "@/lib/page-metadata"
|
|
|
|
export const metadata = pageMetadata("cdp-mode")
|
|
|
|
# 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:
|
|
|
|
1. Reading Chrome's `DevToolsActivePort` file from the default user data directory
|
|
2. Falling back to probing common debugging ports (9222, 9229)
|
|
|
|
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
|
|
```
|
|
|
|
## 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>)</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>--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 <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 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`.
|