Skip to content

feat: add AGENT_BROWSER_CDP env var for --cdp flag #489

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bukacdan wants to merge 2 commits into
base: main
Choose a base branch
from
+27 −4
Open

feat: add AGENT_BROWSER_CDP env var for --cdp flag #489

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
58db404
feat: support AGENT_BROWSER_CDP environment variable for --cdp flag
bukacdan Feb 17, 2026
ce2f64c
docs: document AGENT_BROWSER_CDP environment variable
bukacdan Feb 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -423,7 +423,7 @@ The `-C` flag is useful for modern web apps that use custom clickable elements (
| `--json` | JSON output (for agents) |
| `--full, -f` | Full page screenshot |
| `--headed` | Show browser window (not headless) |
| `--cdp <port\|url>` | Connect via Chrome DevTools Protocol (port or WebSocket URL) |
| `--cdp <port\|url>` | Connect via Chrome DevTools Protocol (port or WebSocket URL; or `AGENT_BROWSER_CDP` env) |
| `--auto-connect` | Auto-discover and connect to running Chrome (or `AGENT_BROWSER_AUTO_CONNECT` env) |
| `--config <path>` | Use a custom config file (or `AGENT_BROWSER_CONFIG` env) |
| `--debug` | Debug output |
Expand Down Expand Up @@ -677,6 +677,10 @@ agent-browser --cdp 9222 snapshot

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

# Or via environment variable
export AGENT_BROWSER_CDP=9222
agent-browser snapshot
```

The `--cdp` flag accepts either:
Expand Down
3 changes: 2 additions & 1 deletion cli/src/flags.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,8 @@ pub fn parse_flags(args: &[String]) -> Flags {
headers: config.headers,
executable_path: env::var("AGENT_BROWSER_EXECUTABLE_PATH").ok()
.or(config.executable_path),
cdp: config.cdp,
cdp: env::var("AGENT_BROWSER_CDP").ok()
.or(config.cdp),
extensions,
profile: env::var("AGENT_BROWSER_PROFILE").ok()
.or(config.profile),
Expand Down
3 changes: 2 additions & 1 deletion cli/src/output.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1933,7 +1933,7 @@ Options:
--json JSON output
--full, -f Full page screenshot
--headed Show browser window (not headless)
--cdp <port> Connect via CDP (Chrome DevTools Protocol)
--cdp <port> Connect via CDP (Chrome DevTools Protocol) (or AGENT_BROWSER_CDP env)
--auto-connect Auto-discover and connect to running Chrome
--session-name <name> Auto-save/restore session state (cookies, localStorage)
--config <path> Use a custom config file (or AGENT_BROWSER_CONFIG env)
Expand Down Expand Up @@ -1973,6 +1973,7 @@ Environment:
AGENT_BROWSER_DEBUG Debug output
AGENT_BROWSER_IGNORE_HTTPS_ERRORS Ignore HTTPS certificate errors
AGENT_BROWSER_PROVIDER Browser provider (ios, browserbase, kernel, browseruse)
AGENT_BROWSER_CDP CDP connection (port or WebSocket URL)
AGENT_BROWSER_AUTO_CONNECT Auto-discover and connect to running Chrome
AGENT_BROWSER_ALLOW_FILE_ACCESS Allow file:// URLs to access local files
AGENT_BROWSER_STREAM_PORT Enable WebSocket streaming on port (e.g., 9223)
Expand Down
16 changes: 15 additions & 1 deletion docs/src/app/cdp-mode/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,20 @@ 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

You can also set the CDP endpoint via environment variable:

```bash
# Set once, use for all commands
export AGENT_BROWSER_CDP=9222
agent-browser snapshot

# Works with URLs too
export AGENT_BROWSER_CDP="wss://browser-service.com/cdp?token=..."
agent-browser snapshot
```

The CLI `--cdp` flag takes precedence over `AGENT_BROWSER_CDP`.

## Auto-Connect

Use `--auto-connect` to automatically discover and connect to a running Chrome instance without specifying a port:
Expand Down Expand Up @@ -86,7 +100,7 @@ This enables control of:
| `--name, -n` | Locator name filter |
| `--exact` | Exact text match |
| `--headed` | Show browser window |
| `--cdp <port\|url>` | CDP connection (port or WebSocket URL) |
| `--cdp <port\|url>` | CDP connection (port or WebSocket URL, or `AGENT_BROWSER_CDP` env) |
| `--auto-connect` | Auto-discover and connect to running Chrome |
| `--debug` | Debug output |

Expand Down
3 changes: 3 additions & 0 deletions skills/agent-browser/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,9 @@ agent-browser --auto-connect snapshot

# Or with explicit CDP port
agent-browser --cdp 9222 snapshot

# Or via environment variable
AGENT_BROWSER_CDP=9222 agent-browser snapshot
```

### Visual Browser (Debugging)
Expand Down