By default, browser state (cookies, localStorage, login sessions) is ephemeral and lost when the browser closes. Use --profile to persist state across browser restarts:

`bash


Use a persistent profile directory

The snapshot command supports filtering to reduce output size:

`bash
agent-browser snapshot # Full accessibility tree
agent-browser snapshot -i # Interactive elements only (buttons, inputs, links)
agent-browser snapshot -i -C # Include cursor-interactive elements (divs with onclick, etc.)
agent-browser snapshot -c # Compact (remove empty structural elements)
agent-browser snapshot -d 3 # Limit depth to 3 levels
agent-browser snapshot -s "#main" # Scope to CSS selector
agent-browser snapshot -i -c -d 5 # Combine options
`

| Option | Description |
|--------|-------------|
| -i, --interactive | Only show interactive elements (buttons, links, inputs) |
| -C, --cursor | Include cursor-interactive elements (cursor:pointer, onclick, tabindex) |
| -c, --compact | Remove empty structural elements |
| -d, --depth | Limit tree depth |
| -s, --selector | Scope to CSS selector |

The -C flag is useful for modern web apps that use custom clickable elements (divs, spans) instead of standard buttons/links.

Options

| Option | Description |
|--------|-------------|
| --session | Use isolated session (or AGENT_BROWSER_SESSION env) |
| --profile | Persistent browser profile directory (or AGENT_BROWSER_PROFILE env) |
| --headers | Set HTTP headers scoped to the URL's origin |
| --executable-path | Custom browser executable (or AGENT_BROWSER_EXECUTABLE_PATH env) |
| --args | Browser launch args, comma or newline separated (or AGENT_BROWSER_ARGS env) |
| --user-agent | Custom User-Agent string (or AGENT_BROWSER_USER_AGENT env) |
| --proxy | Proxy server URL with optional auth (or AGENT_BROWSER_PROXY env) |
| --proxy-bypass | Hosts to bypass proxy (or AGENT_BROWSER_PROXY_BYPASS env) |
| -p, --provider | Cloud browser provider (or AGENT_BROWSER_PROVIDER env) |
| --json | JSON output (for agents) |
| --full, -f | Full page screenshot |
| --name, -n | Locator name filter |
| --exact | Exact text match |
| --headed | Show browser window (not headless) |
| --cdp | Connect via Chrome DevTools Protocol |
| --ignore-https-errors | Ignore HTTPS certificate errors (useful for self-signed certs) |
| --allow-file-access | Allow file:// URLs to access local files (Chromium only) |
| --debug | Debug output |

Selectors

$3

Refs provide deterministic element selection from snapshots:

`bash


1. Get snapshot with refs

`bash
agent-browser click "#id"
agent-browser click ".class"
agent-browser click "div > button"
`

$3

`bash
agent-browser click "text=Submit"
agent-browser click "xpath=//button"
`

$3

`bash
agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "test@test.com"
`

Agent Mode

Use --json for machine-readable output:

`bash
agent-browser snapshot --json


Returns: {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}}

agent-browser get text @e1 --json
agent-browser is visible @e2 --json
`

$3

`bash


1. Navigate and get snapshot

`bash
agent-browser open example.com --headed
`

This opens a visible browser window instead of running headless.

Authenticated Sessions

Use --headers to set HTTP headers for a specific origin, enabling authentication without login flows:

`bash


Headers are scoped to api.example.com only

To set headers for multiple origins, use --headers with each open command:

`bash
agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'
`

For global headers (all domains), use set headers:

`bash
agent-browser set headers '{"X-Custom-Header": "value"}'
`

Custom Browser Executable

Use a custom browser executable instead of the bundled Chromium. This is useful for:
- Serverless deployment: Use lightweight Chromium builds like @sparticuz/chromium (~50MB vs ~684MB)
- System browsers: Use an existing Chrome/Chromium installation
- Custom builds: Use modified browser builds

$3

`bash


Via flag

`typescript
import chromium from '@sparticuz/chromium';
import { BrowserManager } from 'agent-browser';

export async function handler() {
const browser = new BrowserManager();
await browser.launch({
executablePath: await chromium.executablePath(),
headless: true,
});
// ... use browser
}
`

Local Files

Open and interact with local files (PDFs, HTML, etc.) using file:// URLs:

`bash


Enable file access (required for JavaScript to access local files)

The --allow-file-access flag adds Chromium flags (--allow-file-access-from-files, --allow-file-access) that allow file:// URLs to:
- Load and render local files
- Access other local files via JavaScript (XHR, fetch)
- Load local resources (images, scripts, stylesheets)

Note: This flag only works with Chromium. For security, it's disabled by default.

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

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

This enables control of:
- Electron apps
- Chrome/Chromium instances with remote debugging
- WebView2 applications
- Any browser exposing a CDP endpoint

Streaming (Browser Preview)

Stream the browser viewport via WebSocket for live preview or "pair browsing" where a human can watch and interact alongside an AI agent.

$3

Set the AGENT_BROWSER_STREAM_PORT environment variable:

`bash
AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com
`

This starts a WebSocket server on the specified port that streams the browser viewport and accepts input events.

$3

Connect to ws://localhost:9223 to receive frames and send input:

Receive frames:
`json
{
"type": "frame",
"data": "",
"metadata": {
"deviceWidth": 1280,
"deviceHeight": 720,
"pageScaleFactor": 1,
"offsetTop": 0,
"scrollOffsetX": 0,
"scrollOffsetY": 0
}
}
`

Send mouse events:
`json
{
"type": "input_mouse",
"eventType": "mousePressed",
"x": 100,
"y": 200,
"button": "left",
"clickCount": 1
}
`

Send keyboard events:
`json
{
"type": "input_keyboard",
"eventType": "keyDown",
"key": "Enter",
"code": "Enter"
}
`

Send touch events:
`json
{
"type": "input_touch",
"eventType": "touchStart",
"touchPoints": [{ "x": 100, "y": 200 }]
}
`

$3

For advanced use, control streaming directly via the protocol:

`typescript
import { BrowserManager } from 'agent-browser';

const browser = new BrowserManager();
await browser.launch({ headless: true });
await browser.navigate('https://example.com');

// Start screencast
await browser.startScreencast((frame) => {
// frame.data is base64-encoded image
// frame.metadata contains viewport info
console.log('Frame received:', frame.metadata.deviceWidth, 'x', frame.metadata.deviceHeight);
}, {
format: 'jpeg',
quality: 80,
maxWidth: 1280,
maxHeight: 720,
});

// Inject mouse events
await browser.injectMouseEvent({
type: 'mousePressed',
x: 100,
y: 200,
button: 'left',
});

// Inject keyboard events
await browser.injectKeyboardEvent({
type: 'keyDown',
key: 'Enter',
code: 'Enter',
});

// Stop when done
await browser.stopScreencast();
`

Architecture

agent-browser uses a client-daemon architecture:

1. Rust CLI (fast native binary) - Parses commands, communicates with daemon
2. Node.js Daemon - Manages Playwright browser instance
3. Fallback - If native binary unavailable, uses Node.js directly

The daemon starts automatically on first command and persists between commands for fast subsequent operations.

Browser Engine: Uses Chromium by default. The daemon also supports Firefox and WebKit via the Playwright protocol.

Platforms

| Platform | Binary | Fallback |
|----------|--------|----------|
| macOS ARM64 | Native Rust | Node.js |
| macOS x64 | Native Rust | Node.js |
| Linux ARM64 | Native Rust | Node.js |
| Linux x64 | Native Rust | Node.js |
| Windows x64 | Native Rust | Node.js |

Usage with AI Agents

$3

The simplest approach - just tell your agent to use it:

`
Use agent-browser to test the login flow. Run agent-browser --help to see available commands.
`

The --help output is comprehensive and most agents can figure it out from there.

$3

Add the skill to your AI coding assistant for richer context:

`bash
npx skills add vercel-labs/agent-browser
`

This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf.

$3

For more consistent results, add to your project or global instructions file:

`markdown


Browser Automation

Use agent-browser for web automation. Run agent-browser --help for all commands.

Core workflow:
1. agent-browser open - Navigate to page
2. agent-browser snapshot -i - Get interactive elements with refs (@e1, @e2)
3. agent-browser click @e1 / fill @e2 "text" - Interact using refs
4. Re-snapshot after page changes
`

Integrations

$3

Control real Mobile Safari in the iOS Simulator for authentic mobile web testing. Requires macOS with Xcode.

Setup:

`bash


Install Appium and XCUITest driver

`bash


List available iOS simulators

`bash
export AGENT_BROWSER_PROVIDER=ios
export AGENT_BROWSER_IOS_DEVICE="iPhone 16 Pro"
agent-browser open https://example.com
`

| Variable | Description |
|----------|-------------|
| AGENT_BROWSER_PROVIDER | Set to ios to enable iOS mode |
| AGENT_BROWSER_IOS_DEVICE | Device name (e.g., "iPhone 16 Pro", "iPad Pro") |
| AGENT_BROWSER_IOS_UDID | Device UDID (alternative to device name) |

Supported devices: All iOS Simulators available in Xcode (iPhones, iPads), plus real iOS devices.

Note: The iOS provider boots the simulator, starts Appium, and controls Safari. First launch takes ~30-60 seconds; subsequent commands are fast.

#### Real Device Support

Appium also supports real iOS devices connected via USB. This requires additional one-time setup:

1. Get your device UDID:
`bash
xcrun xctrace list devices


or

2. Sign WebDriverAgent (one-time):
`bash


Open the WebDriverAgent Xcode project

In Xcode:
- Select the WebDriverAgentRunner target
- Go to Signing & Capabilities
- Select your Team (requires Apple Developer account, free tier works)
- Let Xcode manage signing automatically

3. Use with agent-browser:
`bash


Connect device via USB, then:

To enable Browserbase, use the -p flag:

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

Or use environment variables for CI/scripts:

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

When enabled, agent-browser connects to a Browserbase session instead of launching a local browser. All commands work identically.

Get your API key and project ID from the Browserbase Dashboard.

$3

Browser Use provides cloud browser infrastructure for AI agents. Use it when running agent-browser in environments where a local browser isn't available (serverless, CI/CD, etc.).

To enable Browser Use, use the -p flag:

`bash
export BROWSER_USE_API_KEY="your-api-key"
agent-browser -p browseruse open https://example.com
`

Or use environment variables for CI/scripts:

`bash
export AGENT_BROWSER_PROVIDER=browseruse
export BROWSER_USE_API_KEY="your-api-key"
agent-browser open https://example.com
`

When enabled, agent-browser connects to a Browser Use cloud session instead of launching a local browser. All commands work identically.

Get your API key from the Browser Use Cloud Dashboard. Free credits are available to get started, with pay-as-you-go pricing after.

$3

Kernel provides cloud browser infrastructure for AI agents with features like stealth mode and persistent profiles.

To enable Kernel, use the -p flag:

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

Or use environment variables for CI/scripts:

`bash
export AGENT_BROWSER_PROVIDER=kernel
export KERNEL_API_KEY="your-api-key"
agent-browser open https://example.com
`

Optional configuration via environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| KERNEL_HEADLESS | Run browser in headless mode (true/false) | false |
| KERNEL_STEALTH | Enable stealth mode to avoid bot detection (true/false) | true |
| KERNEL_TIMEOUT_SECONDS | Session timeout in seconds | 300 |
| KERNEL_PROFILE_NAME | Browser profile name for persistent cookies/logins (created if it doesn't exist) | (none) |

When enabled, agent-browser connects to a Kernel cloud session instead of launching a local browser. All commands work identically.

Profile Persistence: When KERNEL_PROFILE_NAME` is set, the profile will be created if it doesn't already exist. Cookies, logins, and session data are automatically saved back to the profile when the browser session ends, making them available for future sessions.

Get your API key from the Kernel Dashboard.

License

Apache-2.0