# Table of Contents

- [agent-browser | Browser Automation for AI](#agent-browser-browser-automation-for-ai)
- [Installation | agent-browser](#installation-agent-browser)
- [Skills | agent-browser](#skills-agent-browser)
- [Selectors | agent-browser](#selectors-agent-browser)
- [Configuration | agent-browser](#configuration-agent-browser)
- [Commands | agent-browser](#commands-agent-browser)
- [Dashboard | agent-browser](#dashboard-agent-browser)
- [Snapshots | agent-browser](#snapshots-agent-browser)
- [CDP Mode | agent-browser](#cdp-mode-agent-browser)
- [Quick Start | agent-browser](#quick-start-agent-browser)
- [Diffing | agent-browser](#diffing-agent-browser)
- [Sessions | agent-browser](#sessions-agent-browser)
- [Profiler | agent-browser](#profiler-agent-browser)
- [iOS Simulator | agent-browser](#ios-simulator-agent-browser)
- [Security | agent-browser](#security-agent-browser)
- [Browser Use | agent-browser](#browser-use-agent-browser)
- [Browserless | agent-browser](#browserless-agent-browser)
- [Browserbase | agent-browser](#browserbase-agent-browser)
- [Kernel | agent-browser](#kernel-agent-browser)
- [AgentCore | agent-browser](#agentcore-agent-browser)
- [Native Mode | agent-browser](#native-mode-agent-browser)
- [Chrome | agent-browser](#chrome-agent-browser)
- [Lightpanda | agent-browser](#lightpanda-agent-browser)
- [Streaming | agent-browser](#streaming-agent-browser)
- [Changelog | agent-browser](#changelog-agent-browser)
- [Next.js + Vercel | agent-browser](#next-js-vercel-agent-browser)

---

# agent-browser | Browser Automation for AI

Introduction

Copy Page

agent-browser
=============

Browser automation CLI designed for AI agents. Compact text output minimizes context usage. 100% native Rust.

    npm install -g agent-browser      # all platforms
    brew install agent-browser        # macOS
    agent-browser install             # Download Chrome (first time)
    
    # or try without installing
    npx agent-browser open example.com

Features
--------

*   **Agent-first** - Compact text output uses fewer tokens than JSON, designed for AI context efficiency
*   **Ref-based** - Snapshot returns accessibility tree with refs for deterministic element selection
*   **Fast** - Native Rust CLI for instant command parsing
*   **Complete** - 50+ commands for navigation, forms, screenshots, network, storage
*   **Sessions** - Multiple isolated browser instances with separate auth
*   **Cross-platform** - macOS, Linux, Windows with native binaries

Works with
----------

Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Google Gemini, opencode, and any agent that can run shell commands.

Example
-------

    # Navigate and get snapshot
    agent-browser open example.com
    agent-browser snapshot -i
    
    # Output:
    # - heading "Example Domain" [ref=e1]
    # - link "More information..." [ref=e2]
    
    # Interact using refs
    agent-browser click @e2
    agent-browser screenshot page.png
    agent-browser close

Why refs?
---------

The `snapshot` command returns a compact accessibility tree where each element has a unique ref like `@e1`, `@e2`. This provides:

*   **Context-efficient** - Text output uses ~200-400 tokens vs ~3000-5000 for full DOM
*   **Deterministic** - Ref points to exact element from snapshot
*   **Fast** - No DOM re-query needed
*   **AI-friendly** - LLMs parse text output naturally

Architecture
------------

Client-daemon architecture for optimal performance:

1.  **Rust CLI** - Parses commands, communicates with daemon
2.  **Native Daemon** - Pure Rust daemon using direct CDP, manages Chrome via Chrome DevTools Protocol

Daemon starts automatically and persists between commands.

Platforms
---------

Native Rust binaries for macOS (ARM64, x64), Linux (ARM64, x64), and Windows (x64).

Ask AI⌘I

---

# Installation | agent-browser

Installation

Copy Page

Installation
============

Global installation (recommended)
---------------------------------

Installs the native Rust binary for maximum performance:

    npm install -g agent-browser
    agent-browser install  # Download Chrome from Chrome for Testing (first time)

This is the fastest option -- commands run through the native Rust CLI directly with sub-millisecond parsing overhead.

Quick start (no install)
------------------------

    npx agent-browser install   # Download Chrome (first time only)
    npx agent-browser open example.com

Project installation (local dependency)
---------------------------------------

For projects that want to pin the version in `package.json`:

    npm install agent-browser
    npx agent-browser install  # Download Chrome (first time)

Then use via `npx` or `package.json` scripts.

Homebrew (macOS)
----------------

    brew install agent-browser
    agent-browser install  # Download Chrome (first time)

Cargo (Rust)
------------

    cargo install agent-browser
    agent-browser install  # Download Chrome (first time)

Compiles from source (~2-3 min). Requires the Rust toolchain ([rustup.rs](https://rustup.rs/)
).

From source
-----------

    git clone https://github.com/vercel-labs/agent-browser
    cd agent-browser
    pnpm install
    pnpm build
    pnpm build:native
    ./bin/agent-browser install
    pnpm link --global

Linux dependencies
------------------

On Linux, install system dependencies:

    agent-browser install --with-deps

Updating
--------

Upgrade to the latest version:

    agent-browser upgrade

Detects your installation method (npm, Homebrew, or Cargo) and runs the appropriate update command automatically. Displays the version change on success, or informs you if you are already on the latest version.

Custom browser
--------------

Use a custom browser executable instead of bundled Chromium:

*   **Serverless** - Use `@sparticuz/chromium` (~50MB vs ~684MB)
*   **System browser** - Use existing Chrome installation
*   **Custom builds** - Use modified browser builds

    # Via flag
    agent-browser --executable-path /path/to/chromium open example.com
    
    # Via environment variable
    AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com

### Serverless example

Use `@sparticuz/chromium` or similar to obtain a Chromium executable path, then pass it via `--executable-path` or `AGENT_BROWSER_EXECUTABLE_PATH`.

AI agent setup
--------------

agent-browser works with any AI agent out of the box. For richer context:

### AI coding assistants (recommended)

Install the skill for your AI coding assistant:

    npx skills add vercel-labs/agent-browser

This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf. The skill is fetched from the repository and stays up to date automatically.

> **Do not** copy `SKILL.md` from `node_modules` -- it will become stale as new features are added. Always use `npx skills add` or reference the repository version.

### AGENTS.md / CLAUDE.md

Add to your instructions file:

    ## Browser Automation
    
    Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.
    
    Core workflow:
    1. `agent-browser open <url>` - 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

Ask AI⌘I

---

# Skills | agent-browser

Skills

Copy Page

Skills
======

agent-browser ships with skills that teach AI coding agents how to use it for specific workflows. Install a skill and your agent in Cursor, Claude Code, or Codex can automate browser tasks without manual guidance.

Available Skills
----------------

*   **agent-browser** — General browser automation: navigation, snapshots, forms, screenshots, data extraction, sessions, authentication, diffing, and the full command reference.
*   **dogfood** — Systematic exploratory testing. Navigates an app like a real user, finds bugs and UX issues, and produces a structured report with screenshots and repro videos.
*   **electron** — Automate any Electron app (VS Code, Slack, Discord, Figma, etc.) by connecting to its built-in Chrome DevTools Protocol port. This is how agent-browser drives native desktop apps like the Slack macOS app.
*   **slack** — Browser-based Slack automation. Check unreads, navigate channels, search conversations, send messages, and extract data — no API tokens needed.
*   **vercel-sandbox** — Run agent-browser + headless Chrome inside ephemeral Vercel Sandbox microVMs. Works with any Vercel-deployed framework (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.).

Installation
------------

    npx skills add vercel-labs/agent-browser --skill agent-browser
    npx skills add vercel-labs/agent-browser --skill dogfood
    npx skills add vercel-labs/agent-browser --skill electron
    npx skills add vercel-labs/agent-browser --skill slack
    npx skills add vercel-labs/agent-browser --skill vercel-sandbox

After installing, your AI agent will automatically activate the right skill when it encounters a matching request.

agent-browser
-------------

The core skill. Teaches agents the full agent-browser API: the navigate-snapshot-interact-re-snapshot workflow, all commands, command chaining, authentication (auth vault and state persistence), sessions, diffing, JavaScript evaluation, annotated screenshots, semantic locators, and configuration.

Example agent interactions:

*   "Open example.com and fill out the contact form"
*   "Take a screenshot of the dashboard after logging in"
*   "Compare staging and production versions of the homepage"

dogfood
-------

A structured workflow for exploratory testing. The agent opens a target URL, systematically explores the app (navigating pages, testing forms, clicking buttons, checking console errors), and documents every issue it finds with:

*   Numbered repro steps
*   Step-by-step screenshots
*   Repro videos for interactive bugs
*   Severity classification

The output is a markdown report in an output directory, ready to hand to the responsible team. Run it with a single prompt like "dogfood vercel.com" or "QA http://localhost:3000 — focus on the billing page".

electron
--------

Electron apps (VS Code, Slack, Discord, Figma, Notion, Spotify, etc.) are built on Chromium and expose a Chrome DevTools Protocol (CDP) port that agent-browser can connect to. This skill teaches agents how to launch or connect to any Electron app, then use the standard snapshot-interact workflow to automate it. Launch the app with `--remote-debugging-port`, connect, and use the standard snapshot-interact workflow. This is the foundation that the **slack** skill builds on.

slack
-----

Browser-based Slack automation. Connects to an existing Slack session (via `agent-browser connect 9222`) or opens Slack in a new browser, then uses snapshots and element refs to navigate the UI. Covers checking unreads, navigating channels and DMs, searching conversations, extracting message data, and taking screenshots — all without needing Slack API tokens or bot setup.

vercel-sandbox
--------------

Run agent-browser + headless Chrome inside ephemeral Vercel Sandbox microVMs. A Linux VM spins up on demand, executes browser commands, and shuts down automatically. Works with any Vercel-deployed framework (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.).

Key features:

*   Sandbox snapshots for sub-second startup (pre-install system deps, agent-browser, and Chromium)
*   Multi-step workflows with persistent state between commands
*   Automatic OIDC authentication on Vercel, or explicit credentials for local dev
*   Scheduled workflows via Vercel Cron Jobs

Get started with the `@vercel/sandbox` package and the `withBrowser` helper pattern. See the `examples/environments/` directory in the repo for a working demo app.

Source
------

All skill files are in the [`skills/`](https://github.com/vercel-labs/agent-browser/tree/main/skills)
 directory of the repository.

Ask AI⌘I

---

# Selectors | agent-browser

Selectors

Copy Page

Selectors
=========

Refs (recommended)
------------------

Refs provide deterministic element selection from snapshots. Best for AI agents.

    # 1. Get snapshot with refs
    agent-browser snapshot
    # Output:
    # - heading "Example Domain" [ref=e1] [level=1]
    # - button "Submit" [ref=e2]
    # - textbox "Email" [ref=e3]
    # - link "Learn more" [ref=e4]
    
    # 2. Use refs to interact
    agent-browser click @e2                   # Click the button
    agent-browser fill @e3 "test@example.com" # Fill the textbox
    agent-browser get text @e1                # Get heading text
    agent-browser hover @e4                   # Hover the link

### Why refs?

*   **Deterministic** - Ref points to exact element from snapshot
*   **Fast** - No DOM re-query needed
*   **AI-friendly** - LLMs can reliably parse and use refs

CSS selectors
-------------

    agent-browser click "#id"
    agent-browser click ".class"
    agent-browser click "div > button"
    agent-browser click "[data-testid='submit']"

Text & XPath
------------

    agent-browser click "text=Submit"
    agent-browser click "xpath=//button[@type='submit']"

Semantic locators
-----------------

Find elements by role, label, or other semantic properties:

    agent-browser find role button click --name "Submit"
    agent-browser find label "Email" fill "test@test.com"
    agent-browser find placeholder "Search..." fill "query"
    agent-browser find testid "submit-btn" click

Ask AI⌘I

---

# Configuration | agent-browser

Configuration

Copy Page

Configuration
=============

Create an `agent-browser.json` file to set persistent defaults instead of repeating flags on every command.

Config File Locations
---------------------

agent-browser checks two locations, merged in priority order:

| Priority | Location | Scope |
| --- | --- | --- |
| 1 (lowest) | `~/.agent-browser/config.json` | User-level defaults |
| 2   | `./agent-browser.json` | Project-level overrides |
| 3   | `AGENT_BROWSER_*` env vars | Override config values |
| 4 (highest) | CLI flags | Override everything |

Project-level values override user-level values. Environment variables override both. CLI flags always win.

Use `--config <path>` or the `AGENT_BROWSER_CONFIG` environment variable to load a specific config file instead of the default locations:

    agent-browser --config ./ci-config.json open example.com
    AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com

Example Config
--------------

    {
      "headed": true,
      "proxy": "http://localhost:8080",
      "profile": "./browser-data",
      "userAgent": "my-agent/1.0",
      "ignoreHttpsErrors": true
    }

All Options
-----------

Every CLI flag can be set in the config file using its camelCase equivalent:

| Config Key | CLI Flag | Type |
| --- | --- | --- |
| `headed` | `--headed` | boolean |
| `json` | `--json` | boolean |
| `full` | `--full, -f` | boolean |
| `debug` | `--debug` | boolean |
| `session` | `--session` | string |
| `sessionName` | `--session-name` | string |
| `executablePath` | `--executable-path` | string |
| `extensions` | `--extension` | string\[\] |
| `profile` | `--profile` | string |
| `state` | `--state` | string |
| `proxy` | `--proxy` | string |
| `proxyBypass` | `--proxy-bypass` | string |
| `args` | `--args` | string |
| `userAgent` | `--user-agent` | string |
| `provider` | `-p, --provider` | string |
| `device` | `--device` | string |
| `ignoreHttpsErrors` | `--ignore-https-errors` | boolean |
| `allowFileAccess` | `--allow-file-access` | boolean |
| `cdp` | `--cdp` | string |
| `autoConnect` | `--auto-connect` | boolean |
| `colorScheme` | `--color-scheme` | string (`dark`, `light`, `no-preference`) |
| `downloadPath` | `--download-path` | string |
| `contentBoundaries` | `--content-boundaries` | boolean |
| `maxOutput` | `--max-output` | number |
| `allowedDomains` | `--allowed-domains` | string\[\] |
| `actionPolicy` | `--action-policy` | string |
| `confirmActions` | `--confirm-actions` | string |
| `confirmInteractive` | `--confirm-interactive` | boolean |
| `engine` | `--engine` | string (`chrome`, `lightpanda`) |
| `noAutoDialog` | `--no-auto-dialog` | boolean |
| `headers` | `--headers` | string (JSON) |

Common Configurations
---------------------

### Local Development

    {
      "headed": true,
      "profile": "./browser-data"
    }

### Behind a Proxy

    {
      "proxy": "http://proxy.corp.example.com:8080",
      "proxyBypass": "localhost,*.internal.com",
      "ignoreHttpsErrors": true
    }

### CI / Devcontainer

    {
      "args": "--no-sandbox,--disable-gpu",
      "ignoreHttpsErrors": true
    }

### iOS Testing

    {
      "provider": "ios",
      "device": "iPhone 16 Pro"
    }

### AI Agent Security

    {
      "contentBoundaries": true,
      "maxOutput": 50000,
      "allowedDomains": ["your-app.com", "*.your-app.com"],
      "actionPolicy": "./policy.json"
    }

Overriding Boolean Options
--------------------------

Boolean flags accept an optional `true`/`false` value to override config settings:

    agent-browser --headed false open example.com

A bare flag is equivalent to passing `true`:

    agent-browser --headed open example.com       # same as --headed true
    agent-browser --headed true open example.com  # explicit

This applies to all boolean flags: `--headed`, `--debug`, `--json`, `--ignore-https-errors`, `--allow-file-access`, `--auto-connect`, `--content-boundaries`, `--confirm-interactive`.

Extensions Merging
------------------

Extensions from user-level and project-level configs are **concatenated**, not replaced. For example, if `~/.agent-browser/config.json` specifies `["/ext1"]` and `./agent-browser.json` specifies `["/ext2"]`, the result is `["/ext1", "/ext2"]`.

The `AGENT_BROWSER_EXTENSIONS` environment variable and CLI `--extension` flags follow the standard priority rules (env replaces config, CLI appends).

Environment Variables
---------------------

These environment variables configure additional daemon and runtime behavior:

| Variable | Description | Default |
| --- | --- | --- |
| `AGENT_BROWSER_AUTO_CONNECT` | Auto-discover and connect to a running Chrome instance. | (disabled) |
| `AGENT_BROWSER_ALLOW_FILE_ACCESS` | Allow `file://` URLs to access local files. | (disabled) |
| `AGENT_BROWSER_COLOR_SCHEME` | Color scheme preference (`dark`, `light`, `no-preference`). | (none) |
| `AGENT_BROWSER_DOWNLOAD_PATH` | Default directory for browser downloads. | (temp directory) |
| `AGENT_BROWSER_DEFAULT_TIMEOUT` | Default timeout in ms. Keep below 30000 to avoid IPC timeouts. | `25000` |
| `AGENT_BROWSER_SESSION_NAME` | Auto-save/load state persistence name. | (none) |
| `AGENT_BROWSER_STATE_EXPIRE_DAYS` | Auto-delete saved session states older than N days. | `30` |
| `AGENT_BROWSER_ENCRYPTION_KEY` | 64-char hex key for AES-256-GCM session encryption. | (none) |
| `AGENT_BROWSER_EXTENSIONS` | Comma-separated browser extension paths. Extensions work in both headed and headless mode. | (none) |
| `AGENT_BROWSER_HEADED` | Show browser window instead of running headless (`1` to enable). | (disabled) |
| `AGENT_BROWSER_STREAM_PORT` | Override the WebSocket streaming port. By default, an OS-assigned port is used. Set this to bind to a specific port (e.g., `9223`). | OS-assigned |
| `AGENT_BROWSER_IDLE_TIMEOUT_MS` | Auto-shutdown the daemon after N ms of inactivity (no commands received). Useful for ephemeral environments. | (disabled) |
| `AGENT_BROWSER_IOS_DEVICE` | Default iOS device name for the `ios` provider. | (none) |
| `AGENT_BROWSER_IOS_UDID` | Default iOS device UDID for the `ios` provider. | (none) |
| `AGENT_BROWSER_DEBUG` | Enable debug output (`1` to enable). | (disabled) |
| `AGENT_BROWSER_CONTENT_BOUNDARIES` | Wrap page output in boundary markers for LLM safety. | (disabled) |
| `AGENT_BROWSER_MAX_OUTPUT` | Max characters for page output (truncates beyond limit). | (unlimited) |
| `AGENT_BROWSER_ALLOWED_DOMAINS` | Comma-separated allowed domain patterns (e.g., `example.com,*.example.com`). | (unrestricted) |
| `AGENT_BROWSER_ACTION_POLICY` | Path to action policy JSON file. | (none) |
| `AGENT_BROWSER_CONFIRM_ACTIONS` | Comma-separated action categories requiring confirmation. | (none) |
| `AGENT_BROWSER_CONFIRM_INTERACTIVE` | Enable interactive confirmation prompts (auto-denies if stdin is not a TTY). | (disabled) |
| `AGENT_BROWSER_ENGINE` | Browser engine to use: `chrome` (default), `lightpanda`. | `chrome` |
| `AGENT_BROWSER_NO_AUTO_DIALOG` | Disable automatic dismissal of `alert`/`beforeunload` dialogs. | (disabled) |

Error Handling
--------------

*   **Auto-discovered config files** (`~/.agent-browser/config.json`, `./agent-browser.json`) that are missing are silently ignored.
*   **`--config <path>`** with a missing or malformed file exits with an error.
*   **Malformed JSON** in auto-discovered files prints a warning to stderr and continues without that file.
*   **Unknown keys** are silently ignored for forward compatibility.

> **Tip:** If your project-level `agent-browser.json` contains environment-specific values (paths, proxies), consider adding it to `.gitignore`.

Ask AI⌘I

---

# Commands | agent-browser

Commands

Copy Page

Commands
========

Core
----

    agent-browser open <url>              # Navigate (aliases: goto, navigate)
    agent-browser click <sel>             # Click element (--new-tab to open in new tab)
    agent-browser dblclick <sel>          # Double-click
    agent-browser fill <sel> <text>       # Clear and fill
    agent-browser type <sel> <text>       # Type into element
    agent-browser press <key>             # Press key (Enter, Tab, Control+a) (alias: key)
    agent-browser keyboard type <text>    # Type at current focus (no selector needed)
    agent-browser keyboard inserttext <text>  # Insert text without key events
    agent-browser keydown <key>           # Hold key down
    agent-browser keyup <key>             # Release key
    agent-browser hover <sel>             # Hover element
    agent-browser focus <sel>             # Focus element
    agent-browser select <sel> <val>      # Select dropdown option
    agent-browser check <sel>             # Check checkbox
    agent-browser uncheck <sel>           # Uncheck checkbox
    agent-browser scroll <dir> [px]       # Scroll (up/down/left/right, --selector <sel>)
    agent-browser scrollintoview <sel>    # Scroll element into view
    agent-browser drag <src> <dst>        # Drag and drop
    agent-browser upload <sel> <files>    # Upload files
    agent-browser screenshot [path]       # Screenshot (--full for full page)
    agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
    agent-browser screenshot --screenshot-dir ./shots    # Save to custom directory
    agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
    agent-browser pdf <path>              # Save page as PDF
    agent-browser snapshot                # Accessibility tree with refs
    agent-browser eval <js>               # Run JavaScript
    agent-browser connect ​​port|url​​      # Connect to browser via CDP
    agent-browser stream enable [--port <port>]  # Start runtime WebSocket streaming
    agent-browser stream status           # Show runtime streaming state and bound port
    agent-browser stream disable          # Stop runtime WebSocket streaming
    agent-browser close                   # Close browser (aliases: quit, exit)
    agent-browser close --all             # Close all active sessions

Get info
--------

    agent-browser get text <sel>          # Get text content
    agent-browser get html <sel>          # Get innerHTML
    agent-browser get value <sel>         # Get input value
    agent-browser get attr <sel> <attr>   # Get attribute
    agent-browser get title               # Get page title
    agent-browser get url                 # Get current URL
    agent-browser get cdp-url             # Get CDP WebSocket URL
    agent-browser get count <sel>         # Count matching elements
    agent-browser get box <sel>           # Get bounding box
    agent-browser get styles <sel>        # Get computed styles

Check state
-----------

    agent-browser is visible <sel>        # Check if visible
    agent-browser is enabled <sel>        # Check if enabled
    agent-browser is checked <sel>        # Check if checked

Find elements
-------------

Semantic locators with actions (`click`, `fill`, `type`, `hover`, `focus`, `check`, `uncheck`, `text`):

    agent-browser find role <role> <action> [value]
    agent-browser find text <text> <action>
    agent-browser find label <label> <action> [value]
    agent-browser find placeholder <ph> <action> [value]
    agent-browser find alt <text> <action>
    agent-browser find title <text> <action>
    agent-browser find testid <id> <action> [value]
    agent-browser find first <sel> <action> [value]
    agent-browser find last <sel> <action> [value]
    agent-browser find nth <n> <sel> <action> [value]

Options:

*   `--name <name>` -- filter role by accessible name
*   `--exact` -- require exact text match

Examples:

    agent-browser find role button click --name "Submit"
    agent-browser find label "Email" fill "test@test.com"
    agent-browser find alt "Logo" click
    agent-browser find first ".item" click
    agent-browser find last ".item" text
    agent-browser find nth 2 ".card" hover

Wait
----

    agent-browser wait <selector>         # Wait for element
    agent-browser wait <ms>               # Wait for time
    agent-browser wait --text "Welcome"   # Wait for text (substring match)
    agent-browser wait --url "**/dash"    # Wait for URL pattern
    agent-browser wait --load networkidle # Wait for load state
    agent-browser wait --fn "condition"   # Wait for JS condition
    agent-browser wait --download [path]  # Wait for download
    agent-browser wait --fn "!document.body.innerText.includes('Loading...')"  # Wait for text to disappear
    agent-browser wait "#spinner" --state hidden           # Wait for element to disappear

Downloads
---------

    agent-browser download <sel> <path>   # Click element to trigger download
    agent-browser wait --download [path]  # Wait for any download to complete

Use `--download-path <dir>` (or `AGENT_BROWSER_DOWNLOAD_PATH` env) to set a default download directory. Without it, downloads go to a temporary directory that is deleted when the browser closes.

Mouse
-----

    agent-browser mouse move <x> <y>      # Move mouse
    agent-browser mouse down [button]     # Press button
    agent-browser mouse up [button]       # Release button
    agent-browser mouse wheel <dy> [dx]   # Scroll wheel

Clipboard
---------

    agent-browser clipboard read                      # Read text from clipboard
    agent-browser clipboard write "Hello, World!"     # Write text to clipboard
    agent-browser clipboard copy                      # Copy current selection (Ctrl+C)
    agent-browser clipboard paste                     # Paste from clipboard (Ctrl+V)

Settings
--------

    agent-browser set viewport <w> <h> [scale]  # Set viewport size (scale for retina, e.g. 2)
    agent-browser set device <name>       # Emulate device ("iPhone 14")
    agent-browser set geo <lat> <lng>     # Set geolocation
    agent-browser set offline [on|off]    # Toggle offline mode
    agent-browser set headers <json>      # Extra HTTP headers
    agent-browser set credentials <u> <p> # HTTP basic auth
    agent-browser set media [dark|light]  # Emulate color scheme (persists for session)

Use `--color-scheme` for persistent dark/light mode across all commands:

    agent-browser --color-scheme dark open https://example.com

Cookies & storage
-----------------

    agent-browser cookies                 # Get all cookies
    agent-browser cookies set <name> <val> # Set cookie
    agent-browser cookies clear           # Clear cookies
    
    agent-browser storage local           # Get all localStorage
    agent-browser storage local <key>     # Get specific key
    agent-browser storage local set <k> <v>  # Set value
    agent-browser storage local clear     # Clear all
    
    agent-browser storage session         # Same for sessionStorage

Network
-------

    agent-browser network route <url>              # Intercept requests
    agent-browser network route <url> --abort      # Block requests
    agent-browser network route <url> --body <json>  # Mock response
    agent-browser network unroute [url]            # Remove routes
    agent-browser network requests                 # View tracked requests
    agent-browser network requests --clear         # Clear request log
    agent-browser network requests --filter <pat>  # Filter by URL pattern
    agent-browser network requests --type xhr,fetch  # Filter by resource type
    agent-browser network requests --method POST   # Filter by HTTP method
    agent-browser network requests --status 2xx    # Filter by status (200, 2xx, 400-499)
    agent-browser network request <requestId>      # View full request/response detail
    agent-browser network har start                # Start HAR recording
    agent-browser network har stop [output.har]    # Stop and save HAR (temp path if omitted)

Tabs & frames
-------------

    agent-browser tab                     # List tabs
    agent-browser tab new [url]           # New tab
    agent-browser tab <n>                 # Switch to tab
    agent-browser tab close [n]           # Close tab
    agent-browser window new              # Open new browser window
    agent-browser frame <sel>             # Switch to iframe by CSS selector
    agent-browser frame @e3               # Switch to iframe by element ref
    agent-browser frame main              # Back to main frame

### Iframe support

Iframes are detected automatically during snapshots. `Iframe` nodes are resolved and their content is inlined beneath the iframe element in the snapshot output. Refs assigned to elements inside iframes carry frame context, so `click`, `fill`, and other interactions work without manually switching frames.

    agent-browser snapshot -i
    # @e3 [Iframe] "payment-frame"
    #   @e4 [input] "Card number"
    #   @e5 [button] "Pay"
    
    # Interact directly using refs — no frame switch needed
    agent-browser fill @e4 "4111111111111111"
    agent-browser click @e5
    
    # Or switch frame context for scoped snapshots
    agent-browser frame @e3
    agent-browser snapshot -i             # Only elements inside that iframe
    agent-browser frame main              # Return to main frame

The `frame` command accepts element refs (`@e3`), CSS selectors (`"#my-iframe"`), or frame name/URL.

Dialogs
-------

    agent-browser dialog accept [text]    # Accept dialog (with optional prompt text)
    agent-browser dialog dismiss          # Dismiss dialog
    agent-browser dialog status           # Check if a dialog is currently open

By default, `alert` and `beforeunload` dialogs are automatically accepted so they never block the agent. `confirm` and `prompt` dialogs still require explicit handling. Use `--no-auto-dialog` (or `AGENT_BROWSER_NO_AUTO_DIALOG=1`) to disable automatic handling.

When a JavaScript dialog (`alert`, `confirm`, `prompt`) is pending, all command responses include a `warning` field with the dialog type and message.

Streaming
---------

    agent-browser stream enable           # Start runtime WebSocket streaming on an auto-selected port
    agent-browser stream enable --port 9223  # Bind a specific localhost port
    agent-browser stream status           # Show enabled state, port, browser connection, screencasting
    agent-browser stream disable          # Stop runtime streaming and remove the .stream metadata file

Streaming is enabled automatically for all sessions. Use these commands to check status, re-enable on a specific port, or disable streaming.

Debug
-----

    agent-browser trace start [path]      # Start trace
    agent-browser trace stop [path]       # Stop and save trace
    agent-browser profiler start          # Start Chrome DevTools profiling
    agent-browser profiler stop [path]    # Stop and save profile (.json)
    agent-browser record start <path>     # Start video recording (WebM)
    agent-browser record stop             # Stop and save video
    agent-browser record restart <path>   # Stop current and start new recording
    agent-browser console                 # View console messages
    agent-browser console --json          # JSON output with raw CDP args
    agent-browser console --clear         # Clear console log
    agent-browser errors                  # View page errors
    agent-browser errors --clear          # Clear error log
    agent-browser highlight <sel>         # Highlight element
    agent-browser inspect                 # Open Chrome DevTools for the active page

Auth vault
----------

    agent-browser auth save <name> [opts]    # Save auth profile
    agent-browser auth login <name>          # Login using saved credentials
    agent-browser auth list                  # List saved profiles (names and URLs only)
    agent-browser auth show <name>           # Show profile metadata (no passwords)
    agent-browser auth delete <name>         # Delete a saved profile

Save options:

*   `--url <url>` -- login page URL (required)
*   `--username <user>` -- username (required)
*   `--password <pass>` -- password (required unless `--password-stdin`)
*   `--password-stdin` -- read password from stdin (recommended to avoid shell history exposure)
*   `--username-selector <sel>` -- custom CSS selector for username field
*   `--password-selector <sel>` -- custom CSS selector for password field
*   `--submit-selector <sel>` -- custom CSS selector for submit button

`auth login` navigates with `load` and then waits for the username/password/submit selectors to appear before interacting. This improves reliability on SPA login pages where fields render after initial page load.

    echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
    agent-browser auth login github
    agent-browser auth list

Confirmation
------------

When `--confirm-actions` is set, certain action categories return a `confirmation_required` response instead of executing immediately. Use `confirm` or `deny` to approve or reject the action.

    agent-browser confirm <confirmation-id>  # Approve a pending action
    agent-browser deny <confirmation-id>     # Deny a pending action

Pending confirmations auto-deny after 60 seconds.

    agent-browser --confirm-actions eval,download eval "document.title"
    # Returns confirmation_required with ID
    agent-browser confirm c_8f3a1234

State management
----------------

    agent-browser state save <path>       # Save auth state to file
    agent-browser state load <path>       # Load auth state from file
    agent-browser state list              # List saved state files
    agent-browser state show <file>       # Show state summary
    agent-browser state rename <old> <new> # Rename state file
    agent-browser state clear [name]      # Clear states for session name
    agent-browser state clear --all       # Clear all saved states
    agent-browser state clean --older-than <days>  # Delete old states

Sessions
--------

    agent-browser session                 # Show current session name
    agent-browser session list            # List active sessions

Dashboard
---------

    agent-browser dashboard [start]       # Start the dashboard server (default port: 4848)
    agent-browser dashboard start --port <n>  # Start on a specific port
    agent-browser dashboard stop          # Stop the dashboard server
    agent-browser dashboard install       # Install the dashboard files

Navigation
----------

    agent-browser back                    # Go back
    agent-browser forward                 # Go forward
    agent-browser reload                  # Reload page

Global options
--------------

    --session <name>         # Isolated browser session
    --session-name <name>    # Auto-save/restore session state (cookies, localStorage)
    --profile <path>         # Persistent browser profile directory
    --state <path>           # Load storage state from JSON file
    --headers <json>         # HTTP headers scoped to URL's origin
    --executable-path <path> # Custom browser executable
    --extension <path>       # Load browser extension (repeatable)
    --args <args>            # Browser launch args (comma separated)
    --user-agent <ua>        # Custom User-Agent string
    --proxy <url>            # Proxy server URL
    --proxy-bypass <hosts>   # Hosts to bypass proxy
    --ignore-https-errors    # Ignore HTTPS certificate errors
    --allow-file-access      # Allow file:// URLs to access local files (Chromium only)
    -p, --provider <name>    # Browser provider (ios, browserbase, kernel, browseruse, browserless)
    --device <name>          # iOS device name (e.g., "iPhone 15 Pro")
    --json                   # JSON output (for scripts)
    --annotate               # Annotated screenshot with numbered element labels
    --screenshot-dir <path>   # Default screenshot output directory (or AGENT_BROWSER_SCREENSHOT_DIR)
    --screenshot-quality <n>  # JPEG quality 0-100 (or AGENT_BROWSER_SCREENSHOT_QUALITY)
    --screenshot-format <fmt> # Format: png (default), jpeg (or AGENT_BROWSER_SCREENSHOT_FORMAT)
    --headed                 # Show browser window (not headless)
    --cdp ​​port|url​​         # Connect via Chrome DevTools Protocol (port or WebSocket URL)
    --auto-connect           # Auto-discover and connect to running Chrome
    --color-scheme <scheme>  # Color scheme: dark, light, no-preference
    --download-path <path>   # Default download directory
    --content-boundaries     # Wrap page output in boundary markers for LLM safety
    --max-output <chars>     # Truncate page output to N characters
    --allowed-domains <list> # Comma-separated allowed domain patterns
    --action-policy <path>   # Path to action policy JSON file
    --confirm-actions <list> # Action categories requiring confirmation
    --confirm-interactive    # Interactive confirmation prompts (auto-denies if stdin is not a TTY)
    --config <path>          # Use a custom config file
    --debug                  # Debug output

Batch execution
---------------

Execute multiple commands in a single invocation by piping a JSON array of string arrays to `batch`:

    echo '[\
      ["open", "https://example.com"],\
      ["snapshot", "-i"],\
      ["click", "@e1"],\
      ["screenshot", "result.png"]\
    ]' | agent-browser batch --json
    
    # Stop on first error
    agent-browser batch --bail < commands.json

| Option | Description |
| --- | --- |
| `--bail` | Stop on first error (default: continue all commands) |
| `--json` | Output results as a JSON array |

Command chaining
----------------

Chain commands with `&&` in a single shell invocation. The browser persists via a background daemon, so chaining works naturally and is more efficient than separate calls:

    agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
    agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3
    agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

Use `&&` when you don't need to read intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs, then interact with those refs).

Local files
-----------

Open local files (PDFs, HTML) using `file://` URLs:

    agent-browser --allow-file-access open file:///path/to/document.pdf
    agent-browser --allow-file-access open file:///path/to/page.html
    agent-browser screenshot output.png

The `--allow-file-access` flag enables JavaScript to access other local files. Chromium only.

Ask AI⌘I

---

# Dashboard | agent-browser

Dashboard

Copy Page

Observability Dashboard
=======================

Monitor agent-browser sessions in real time with a local web dashboard showing a live browser viewport and command activity feed.

Install
-------

Download the dashboard once:

    agent-browser dashboard install

This downloads the dashboard to `~/.agent-browser/dashboard/` and is served directly by the daemon when streaming is enabled.

Usage
-----

Start the dashboard server and open any session -- it appears automatically:

    agent-browser dashboard start
    agent-browser open example.com

Then open `http://localhost:4848` in your browser to see the live dashboard.

All sessions automatically stream to the dashboard. No extra flags are needed.

### Custom stream port

By default each session binds its WebSocket stream server to an OS-assigned port. To use a specific port, set the `AGENT_BROWSER_STREAM_PORT` environment variable:

    AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com

You can also use the runtime commands to control streaming on a running session:

    agent-browser stream enable --port 9223
    agent-browser stream status
    agent-browser stream disable

Dashboard features
------------------

The dashboard is a single-page web app with three areas:

| Area | Description |
| --- | --- |
| **Live viewport** | Real-time JPEG frames from the browser, rendered to a canvas element |
| **Activity feed** | Chronological stream of commands, results, and console messages with expandable details |
| **Session creation** | Create new sessions from the dashboard with local engines (Chrome, Lightpanda) or cloud providers (AgentCore, Browserbase, Browserless, Browser Use, Kernel) |
| **Status bar** | Connection status, viewport dimensions, and WebSocket endpoint |

WebSocket protocol
------------------

The dashboard connects to the same WebSocket endpoint used by [Streaming](https://agent-browser.dev/streaming)
, with additional message types for observability:

### Command events

Sent when a command begins executing:

    {
      "type": "command",
      "action": "click",
      "id": "r123",
      "params": { "selector": "@e5" },
      "timestamp": 1711367000000
    }

### Result events

Sent when a command finishes:

    {
      "type": "result",
      "id": "r123",
      "action": "click",
      "success": true,
      "data": {},
      "duration_ms": 45,
      "timestamp": 1711367000045
    }

### Console events

Sent when the browser logs to the console:

    {
      "type": "console",
      "level": "log",
      "text": "Page loaded",
      "args": [{"type": "string", "value": "Page loaded"}],
      "timestamp": 1711367000100
    }

The `args` array contains the raw CDP `Runtime.consoleAPICalled` arguments for programmatic access. Object arguments include preview data (e.g. `{userId: "abc", count: 42}` instead of `"Object"`).

These are in addition to the existing `frame`, `status`, and `error` message types documented on the [Streaming](https://agent-browser.dev/streaming)
 page.

Architecture
------------

The dashboard is a Next.js static export (`output: 'export'`) that produces plain HTML, CSS, and JS. It lives at `packages/dashboard/` in the monorepo and is built with:

    pnpm build:dashboard

The built files are served by the daemon's stream server on the same port used for WebSocket connections. Plain HTTP requests serve the dashboard, while WebSocket upgrade requests are handled as before.

When the dashboard is not installed, visiting the HTTP endpoint shows instructions to run `agent-browser dashboard install`.

Ask AI⌘I

---

# Snapshots | agent-browser

Snapshots

Copy Page

Snapshots
=========

The `snapshot` command returns a compact accessibility tree with refs for element interaction.

Options
-------

Filter output to reduce size:

    agent-browser snapshot                    # Full accessibility tree
    agent-browser snapshot -i                 # Interactive elements only (recommended)
    agent-browser snapshot -c                 # Compact (remove empty 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 interactive elements (buttons, links, inputs) |
| `-c, --compact` | Remove empty structural elements |
| `-d, --depth` | Limit tree depth |
| `-s, --selector` | Scope to CSS selector |

Output format
-------------

The default text output is compact and AI-friendly:

    agent-browser snapshot -i
    # Output:
    # @e1 [heading] "Example Domain" [level=1]
    # @e2 [button] "Submit"
    # @e3 [input type="email"] placeholder="Email"
    # @e4 [link] "Learn more"

Using refs
----------

Refs from the snapshot map directly to commands:

    agent-browser click @e2      # Click the Submit button
    agent-browser fill @e3 "a@b.com"  # Fill the email input
    agent-browser get text @e1        # Get heading text

Ref lifecycle
-------------

Refs are invalidated when the page changes. Always re-snapshot after navigation or DOM updates:

    agent-browser click @e4      # Navigates to new page
    agent-browser snapshot -i    # Get fresh refs
    agent-browser click @e1      # Use new refs

Annotated screenshots
---------------------

For visual context alongside text snapshots, use `screenshot --annotate` to overlay numbered labels on interactive elements. Each label `[N]` maps to ref `@eN`:

In native mode, annotated screenshots currently work on the CDP-backed browser path (Chromium/Lightpanda). The Safari/WebDriver backend does not yet support `--annotate`.

    agent-browser screenshot --annotate ./page.png
    # -> Screenshot saved to ./page.png
    #    [1] @e1 button "Submit"
    #    [2] @e2 link "Home"
    #    [3] @e3 textbox "Email"
    agent-browser click @e2

Annotated screenshots also cache refs, so you can interact with elements immediately. This is useful when the text snapshot is insufficient -- unlabeled icons, canvas content, or visual layout verification.

Iframes
-------

Snapshots automatically detect and inline iframe content. Each `Iframe` node in the main frame is resolved and its child accessibility tree is included directly beneath it. Refs assigned to elements inside iframes carry frame context, so interactions work without switching frames first.

    agent-browser snapshot -i
    # @e1 [heading] "Checkout"
    # @e2 [Iframe] "payment-frame"
    #   @e3 [input] "Card number"
    #   @e4 [button] "Pay"
    
    agent-browser fill @e3 "4111111111111111"
    agent-browser click @e4

Only one level of iframe nesting is expanded. Cross-origin iframes that block accessibility tree access and empty iframes are silently omitted.

To scope a snapshot to a single iframe, switch into it first:

    agent-browser frame @e2
    agent-browser snapshot -i       # Only elements inside that iframe
    agent-browser frame main        # Return to main frame

Best practices
--------------

1.  Use `-i` to reduce output to actionable elements
2.  Re-snapshot after page changes to get updated refs
3.  Scope with `-s` for specific page sections
4.  Use `-d` to limit depth on complex pages
5.  Use `screenshot --annotate` when visual context is needed alongside refs

JSON output
-----------

For programmatic parsing in scripts:

    agent-browser snapshot --json
    # {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}}

Note: JSON uses more tokens than text output. The default text format is preferred for AI agents.

Ask AI⌘I

---

# CDP Mode | agent-browser

CDP Mode

Copy Page

CDP Mode
========

Connect to an existing browser via Chrome DevTools Protocol:

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

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

    # 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)
3.  If HTTP-based discovery (`/json/version`, `/json/list`) fails, falling back to a direct WebSocket connection

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

Use `--color-scheme` to set a persistent preference when connecting via CDP:

    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:

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

| Option | Description |
| --- | --- |
| `--session <name>` | Use isolated session |
| `--profile <path>` | Persistent browser profile directory |
| `-p <provider>` | Cloud browser provider (`browserbase`, `browseruse`, `kernel`, `browserless`) |
| `--headers <json>` | HTTP headers scoped to origin |
| `--executable-path` | Custom browser executable |
| `--args <args>` | Browser launch args (comma-separated) |
| `--user-agent <ua>` | Custom User-Agent string |
| `--proxy <url>` | Proxy server URL |
| `--proxy-bypass <hosts>` | Hosts to bypass proxy |
| `--json` | JSON output for scripts |
| `--name, -n` | Locator name filter |
| `--exact` | Exact text match |
| `--headed` | Show browser window |
| `--cdp <port\|url>` | CDP connection (port or WebSocket URL) |
| `--auto-connect` | Auto-discover and connect to running Chrome |
| `--color-scheme <scheme>` | Persistent color scheme (`dark`, `light`, `no-preference`) |
| `--debug` | Debug output |

Cloud providers
---------------

Use the `-p` flag to connect to a cloud browser provider instead of launching a local browser:

    agent-browser -p browserbase open https://example.com

See the [Providers](https://agent-browser.dev/providers/browser-use)
 section for setup and configuration of each supported provider: [Browser Use](https://agent-browser.dev/providers/browser-use)
, [Browserbase](https://agent-browser.dev/providers/browserbase)
, [Browserless](https://agent-browser.dev/providers/browserless)
, and [Kernel](https://agent-browser.dev/providers/kernel)
.

Ask AI⌘I

---

# Quick Start | agent-browser

Quick Start

Copy Page

Quick Start
===========

Core workflow
-------------

Every browser automation follows this pattern:

    # 1. Navigate
    agent-browser open example.com
    
    # 2. Snapshot to get element refs
    agent-browser snapshot -i
    # Output:
    # @e1 [heading] "Example Domain"
    # @e2 [link] "More information..."
    
    # 3. Interact using refs
    agent-browser click @e2
    
    # 4. Re-snapshot after page changes
    agent-browser snapshot -i

Common commands
---------------

    agent-browser open example.com
    agent-browser snapshot -i                # Get interactive elements with refs
    agent-browser click @e2                  # Click by ref
    agent-browser fill @e3 "test@example.com" # Fill input by ref
    agent-browser get text @e1               # Get text content
    agent-browser screenshot                 # Save to temp directory
    agent-browser screenshot page.png        # Save to specific path
    agent-browser close

Traditional selectors
---------------------

CSS selectors and semantic locators also supported:

    agent-browser click "#submit"
    agent-browser fill "#email" "test@example.com"
    agent-browser find role button click --name "Submit"

Headed mode
-----------

Show browser window for debugging:

    agent-browser open example.com --headed

Wait for content
----------------

    agent-browser wait @e1                   # Wait for element
    agent-browser wait --load networkidle    # Wait for network idle
    agent-browser wait --url "**/dashboard"  # Wait for URL pattern
    agent-browser wait 2000                  # Wait milliseconds

Command chaining
----------------

Chain commands with `&&` in a single shell call. The browser persists via a background daemon, so chaining is safe and efficient:

    # Open, wait, and snapshot in one call
    agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
    
    # Chain multiple interactions
    agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3
    
    # Navigate and capture
    agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

Use `&&` when you don't need intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs before interacting).

JSON output
-----------

For programmatic parsing in scripts:

    agent-browser snapshot --json
    agent-browser get text @e1 --json

Note: The default text output is more compact and preferred for AI agents.

Ask AI⌘I

---

# Diffing | agent-browser

Diffing

Copy Page

Diffing
=======

Compare page states to detect changes -- structurally via accessibility tree snapshots, visually via pixel comparison, or across two different URLs.

Verify an action changed the page

$ agent-browser snapshot -i

$ agent-browser fill @e3 "test@example.com"

$ agent-browser click @e4

$ agent-browser diff snapshot

heading "Sign Up" \[ref=e1\]

text "Create your account" \[ref=e2\]

\- textbox "Email" \[ref=e3\]

\+ textbox "Email" \[ref=e3\]: "test@example.com"

\- button "Submit" \[ref=e4\]

\+ button "Submit" \[ref=e4\] \[disabled\]

\+ status "Sending..." \[ref=e7\]

link "Already have an account?" \[ref=e5\]

3 additions, 2 removals, 3 unchanged

Catch a visual regression

$ agent-browser diff screenshot --baseline before-deploy.png

✗ 2.37% pixels differ

Diff image: ~/.agent-browser/tmp/diffs/diff-1708473621.png

1,137 different / 48,000 total pixels

Baseline

Submit

Current

Submit

Diff

Submit

Commands
--------

| Command | Description |
| --- | --- |
| `diff snapshot` | Compare current snapshot to last snapshot in session |
| `diff snapshot --baseline <file>` | Compare current snapshot to a saved file |
| `diff screenshot --baseline <file>` | Visual pixel diff against a baseline image |
| `diff url <url1> <url2>` | Compare two pages (snapshot + optional screenshot) |

Snapshot diff
-------------

Compares the accessibility tree between two points in time using a line-level text diff.

    # Compare against the last snapshot taken in this session
    agent-browser diff snapshot
    
    # Compare against a saved baseline file
    agent-browser diff snapshot --baseline before.txt
    
    # Scope to a specific part of the page
    agent-browser diff snapshot --selector "#main" --compact

Without `--baseline`, the command automatically compares against the most recent snapshot taken in the current session. This is the primary use case for agents verifying that an action had the intended effect.

### Options

| Flag | Description |
| --- | --- |
| `-b, --baseline <file>` | Path to a saved snapshot file to compare against |
| `-s, --selector <sel>` | Scope the current snapshot to a CSS selector or @ref |
| `-c, --compact` | Use compact snapshot format |
| `-d, --depth <n>` | Limit snapshot tree depth |

### Output

The diff uses `+` for added lines and `-` for removed lines, similar to unified diff format. A summary line shows the count of additions, removals, and unchanged lines.

    - button "Submit" [ref=e2]
    + button "Submit" [ref=e2] [disabled]
      3 additions, 2 removals, 41 unchanged

Screenshot diff
---------------

Compares the current page screenshot against a baseline image at the pixel level. Produces a diff image with changed pixels highlighted in red.

    # Basic visual diff
    agent-browser diff screenshot --baseline before.png
    
    # Save diff image to a specific path
    agent-browser diff screenshot --baseline before.png --output diff.png
    
    # Adjust threshold and scope to element
    agent-browser diff screenshot --baseline before.png --threshold 0.2 --selector "#hero"

### Options

| Flag | Description |
| --- | --- |
| `-b, --baseline <file>` | Baseline PNG/JPEG image to compare against (required) |
| `-o, --output <file>` | Path for the generated diff image (default: temp dir) |
| `-t, --threshold <0-1>` | Color distance threshold (default: 0.1). Higher = more tolerant |
| `-s, --selector <sel>` | Scope the current screenshot to an element |
| `--full` | Take a full-page screenshot |

### Output

Reports the diff image path, number of different pixels, and mismatch percentage. The diff image shows unchanged pixels dimmed with changed pixels in red.

If the baseline and current images have different dimensions, the command reports a dimension mismatch instead of attempting pixel comparison.

URL diff
--------

Compares two pages by navigating to each in sequence and diffing the results.

    # Compare two URLs (snapshot diff)
    agent-browser diff url https://staging.example.com https://prod.example.com
    
    # Include visual comparison
    agent-browser diff url https://v1.example.com https://v2.example.com --screenshot
    
    # Full-page screenshot comparison
    agent-browser diff url https://v1.example.com https://v2.example.com --screenshot --full

The command navigates to the first URL, captures state, then navigates to the second URL and captures again. Snapshot diff is always included. Screenshot diff requires the `--screenshot` flag.

After completion, the browser remains on the second URL.

### Options

| Flag | Description |
| --- | --- |
| `--screenshot` | Also perform visual screenshot comparison |
| `--full` | Use full-page screenshots |
| `--wait-until <strategy>` | Navigation wait strategy: `load`, `domcontentloaded`, `networkidle` (default: `load`) |
| `-s, --selector <sel>` | Scope snapshots to a CSS selector or @ref |
| `-c, --compact` | Use compact snapshot format |
| `-d, --depth <n>` | Limit snapshot tree depth |

Use cases
---------

### Verifying agent actions

The most common use case: confirm that an action (click, fill, submit) changed the page as expected.

    agent-browser snapshot -i          # Take interactive-only snapshot (baseline)
    agent-browser fill @e3 "test@example.com"
    agent-browser diff snapshot        # Compare current snapshot to the baseline

### Monitoring for changes

Periodically compare a page against a saved baseline to detect updates.

    # Save baseline
    agent-browser open https://example.com && agent-browser snapshot > baseline.txt
    
    # Later, check for changes
    agent-browser open https://example.com && agent-browser diff snapshot --baseline baseline.txt

### Visual regression testing

Compare screenshots before and after a deploy to catch unintended visual changes.

    agent-browser open https://staging.example.com && agent-browser screenshot baseline.png
    # ... deploy happens ...
    agent-browser open https://staging.example.com && agent-browser diff screenshot --baseline baseline.png

### Comparing environments

Diff staging against production to verify parity.

    agent-browser diff url https://staging.example.com https://prod.example.com --screenshot

Ask AI⌘I

---

# Sessions | agent-browser

Sessions

Copy Page

Sessions
========

Run multiple isolated browser instances:

    # Different sessions
    agent-browser --session agent1 open site-a.com
    agent-browser --session agent2 open site-b.com
    
    # Or via environment variable
    AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"
    
    # List active sessions
    agent-browser session list
    # Output:
    # Active sessions:
    # -> default
    #    agent1
    
    # Show current session
    agent-browser session

Session isolation
-----------------

Each session has its own:

*   Browser instance
*   Cookies and storage
*   Navigation history
*   Authentication state

Persistent profiles
-------------------

By default, browser state is lost when the browser closes. Use `--profile` to persist state across restarts:

    # Use a persistent profile directory
    agent-browser --profile ~/.myapp-profile open myapp.com
    
    # Login once, then reuse the authenticated session
    agent-browser --profile ~/.myapp-profile open myapp.com/dashboard
    
    # Or via environment variable
    AGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com

The profile directory stores:

*   Cookies and localStorage
*   IndexedDB data
*   Service workers
*   Browser cache
*   Login sessions

Import auth from your browser
-----------------------------

If you are already logged in to a site in Chrome, you can grab that auth state and reuse it in agent-browser. This is the fastest way to bypass login flows, OAuth, SSO, or 2FA.

**Step 1:** Start Chrome with remote debugging:

    # macOS
    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
    
    # Linux
    google-chrome --remote-debugging-port=9222

Log in to your target site(s) in this Chrome window.

`--remote-debugging-port` exposes full browser control on localhost. Any local process can connect. Only use on trusted machines and close Chrome when done.

**Step 2:** Connect and save the authenticated state:

    agent-browser --auto-connect state save ./my-auth.json

**Step 3:** Use the saved auth in future sessions:

    # Load auth at launch
    agent-browser --state ./my-auth.json open https://app.example.com/dashboard
    
    # Or load into an existing session
    agent-browser state load ./my-auth.json
    agent-browser open https://app.example.com/dashboard

Combine with `--session-name` so the imported auth auto-persists across restarts:

    agent-browser --session-name myapp state load ./my-auth.json
    # From now on, state auto-saves/restores for "myapp"

State files contain session tokens in plaintext. Add them to `.gitignore` and delete when no longer needed. For encryption at rest, see [State encryption](https://agent-browser.dev/sessions#state-encryption)
 below.

Session persistence
-------------------

Use `--session-name` to automatically save and restore cookies and localStorage across browser restarts:

    # Auto-save/load state for "twitter" session
    agent-browser --session-name twitter open twitter.com
    
    # Login once, then state persists automatically
    agent-browser --session-name twitter click "#login"
    
    # Or via environment variable
    export AGENT_BROWSER_SESSION_NAME=twitter
    agent-browser open twitter.com

State files are stored in `~/.agent-browser/sessions/` and automatically loaded on daemon start.

### Session name rules

Session names must contain only alphanumeric characters, hyphens, and underscores:

    # Valid session names
    agent-browser --session-name my-project open example.com
    agent-browser --session-name test_session_v2 open example.com
    
    # Invalid (will be rejected)
    agent-browser --session-name "../bad" open example.com    # path traversal
    agent-browser --session-name "my session" open example.com # spaces
    agent-browser --session-name "foo/bar" open example.com    # slashes

State encryption
----------------

Encrypt saved state files (cookies, localStorage) using AES-256-GCM:

    # Generate a 256-bit key (64 hex characters)
    openssl rand -hex 32
    
    # Set the encryption key
    export AGENT_BROWSER_ENCRYPTION_KEY=<your-64-char-hex-key>
    
    # State files are now encrypted automatically
    agent-browser --session-name secure-session open example.com
    
    # List states shows encryption status
    agent-browser state list

State auto-expiration
---------------------

Automatically delete old state files to prevent accumulation:

    # Set expiration (default: 30 days)
    export AGENT_BROWSER_STATE_EXPIRE_DAYS=7
    
    # Manually clean old states
    agent-browser state clean --older-than 7

State management commands
-------------------------

    # List all saved states
    agent-browser state list
    
    # Show state summary (cookies, origins, domains)
    agent-browser state show my-session-default.json
    
    # Rename a state file
    agent-browser state rename old-name new-name
    
    # Clear states for a specific session name
    agent-browser state clear my-session
    
    # Clear all saved states
    agent-browser state clear --all
    
    # Manual save/load (for custom paths)
    agent-browser state save ./backup.json
    agent-browser state load ./backup.json

Authenticated sessions
----------------------

Use `--headers` to set HTTP headers for a specific origin:

    # Headers scoped to api.example.com only
    agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'
    
    # Requests to api.example.com include the auth header
    agent-browser snapshot -i --json
    agent-browser click @e2
    
    # Navigate to another domain - headers NOT sent
    agent-browser open other-site.com

Useful for:

*   **Skipping login flows** - Authenticate via headers
*   **Switching users** - Different auth tokens per session
*   **API testing** - Access protected endpoints
*   **Security** - Headers scoped to origin, not leaked

Multiple origins
----------------

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

Global headers
--------------

For headers on all domains:

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

Environment variables
---------------------

| Variable | Description |
| --- | --- |
| `AGENT_BROWSER_SESSION` | Browser session ID (default: "default") |
| `AGENT_BROWSER_SESSION_NAME` | Auto-save/load state persistence name |
| `AGENT_BROWSER_ENCRYPTION_KEY` | 64-char hex key for AES-256-GCM encryption |
| `AGENT_BROWSER_STATE_EXPIRE_DAYS` | Auto-delete states older than N days (default: 30) |

Ask AI⌘I

---

# Profiler | agent-browser

Profiler

Copy Page

Profiler
========

Capture Chrome DevTools performance profiles during browser automation. Use profiles to diagnose slow page loads, expensive JavaScript, layout thrashing, and other performance bottlenecks in agentic workflows.

Basic usage
-----------

    # Start profiling
    agent-browser profiler start
    
    # Perform actions
    agent-browser navigate https://example.com
    agent-browser click "#button"
    
    # Stop and save profile
    agent-browser profiler stop ./trace.json

The output JSON file can be loaded into Chrome DevTools, Perfetto UI, or any tool that accepts Chrome Trace Event format.

Commands
--------

| Command | Description |
| --- | --- |
| `profiler start` | Start recording a performance profile |
| `profiler start --categories <list>` | Start with custom trace categories |
| `profiler stop [path]` | Stop profiling and save to file |

Trace categories
----------------

The `--categories` flag accepts a comma-separated list of Chrome trace categories.

    agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"

Default categories include `devtools.timeline`, `v8.execute`, `blink`, `blink.user_timing`, `latencyInfo`, `renderer.scheduler`, `toplevel`, and several `disabled-by-default-*` categories for detailed CPU profiling and call stack analysis.

### Common categories

| Category | What it captures |
| --- | --- |
| `devtools.timeline` | Standard DevTools performance events |
| `v8.execute` | Time spent running JavaScript |
| `blink` | Renderer events (layout, paint, style) |
| `blink.user_timing` | `performance.mark()` and `performance.measure()` calls |
| `latencyInfo` | Input-to-display latency |
| `disabled-by-default-v8.cpu_profiler` | Sampling-based JS CPU profiling |

Output format
-------------

The output is a JSON file in Chrome Trace Event format:

    {
      "traceEvents": [\
        {\
          "cat": "devtools.timeline",\
          "name": "RunTask",\
          "ph": "X",\
          "ts": 12345,\
          "dur": 100,\
          "pid": 1,\
          "tid": 1\
        }\
      ],
      "metadata": {
        "clock-domain": "LINUX_CLOCK_MONOTONIC"
      }
    }

The `metadata.clock-domain` field reflects the host platform (Linux or macOS). On Windows it is omitted.

Viewing profiles
----------------

*   **Chrome DevTools** -- Performance panel > Load profile
*   **Perfetto** -- https://ui.perfetto.dev/ (drag and drop the JSON file)
*   **Trace Viewer** -- `chrome://tracing` in any Chromium browser

Use cases
---------

*   **Page load analysis** -- Profile navigation to identify slow resources, long tasks, or layout shifts
*   **Interaction profiling** -- Measure the cost of clicks, form fills, and other user interactions
*   **CI regression checks** -- Capture profiles per build and compare trace data over time
*   **Agent workflow optimization** -- Find which steps in an agentic flow are most expensive

Limitations
-----------

*   Only works with Chromium-based browsers (Chrome, Edge). Not supported on Firefox or WebKit.
*   Trace data accumulates in memory while profiling is active (capped at 5 million events). Stop profiling promptly after the area of interest.
*   Data collection on stop has a 30-second timeout. If the browser is unresponsive, the stop command may fail.
*   When no output path is provided, the profile is saved to an auto-generated path under the agent-browser temp directory.

Ask AI⌘I

---

# iOS Simulator | agent-browser

iOS Simulator

Copy Page

iOS Simulator
=============

Control real Mobile Safari in the iOS Simulator for authentic mobile web testing. Uses Appium with XCUITest for native automation.

Requirements
------------

*   macOS with Xcode installed
*   iOS Simulator runtimes (download via Xcode)
*   Appium with XCUITest driver

Setup
-----

    # Install Appium globally
    npm install -g appium
    
    # Install the XCUITest driver for iOS
    appium driver install xcuitest

List available devices
----------------------

See all iOS simulators available on your system:

    agent-browser device list
    
    # Output:
    # Available iOS Simulators:
    #
    #   ○ iPhone 16 Pro (iOS 18.0)
    #     F21EEC0D-7618-419F-811B-33AF27A8B2FD
    #   ○ iPhone 16 Pro Max (iOS 18.0)
    #     50402807-C9B8-4D37-9F13-2E00E782C744
    #   ○ iPad Pro 13-inch (M4) (iOS 18.0)
    #     3A6C6436-B909-4593-866D-91D1062BB070
    #   ...

Basic usage
-----------

Use the `-p ios` flag to enable iOS mode. The workflow is identical to desktop:

    # Launch Safari on iPhone 16 Pro
    agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
    
    # Get snapshot with refs (same as desktop)
    agent-browser -p ios snapshot -i
    
    # Interact using refs
    agent-browser -p ios tap @e1
    agent-browser -p ios fill @e2 "text"
    
    # Take screenshot
    agent-browser -p ios screenshot mobile.png
    
    # Close session (shuts down simulator)
    agent-browser -p ios close

Mobile-specific commands
------------------------

    # Swipe gestures
    agent-browser -p ios swipe up
    agent-browser -p ios swipe down
    agent-browser -p ios swipe left
    agent-browser -p ios swipe right
    
    # Swipe with distance (pixels)
    agent-browser -p ios swipe up 500
    
    # Tap (alias for click, semantically clearer for touch)
    agent-browser -p ios tap @e1

Environment variables
---------------------

Configure iOS mode via environment variables:

    export AGENT_BROWSER_PROVIDER=ios
    export AGENT_BROWSER_IOS_DEVICE="iPhone 16 Pro"
    
    # Now all commands use iOS
    agent-browser open https://example.com
    agent-browser snapshot -i
    agent-browser tap @e1

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

Supported devices
-----------------

All iOS Simulators available in Xcode are supported, including:

*   All iPhone models (iPhone 15, 16, 17, SE, etc.)
*   All iPad models (iPad Pro, iPad Air, iPad mini, etc.)
*   Multiple iOS versions (17.x, 18.x, etc.)

**Real devices** are also supported via USB connection (see below).

Real device support
-------------------

Appium can control Safari on real iOS devices connected via USB. This requires additional one-time setup.

### 1\. Get your device UDID

    # List connected devices
    xcrun xctrace list devices
    
    # Or via system profiler
    system_profiler SPUSBDataType | grep -A 5 "iPhone\|iPad"

### 2\. Sign WebDriverAgent (one-time)

WebDriverAgent needs to be signed with your Apple Developer certificate to run on real devices.

    # Open the WebDriverAgent Xcode project
    cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
    open WebDriverAgent.xcodeproj

In Xcode:

1.  Select the `WebDriverAgentRunner` target
2.  Go to Signing & Capabilities
3.  Select your Team (requires Apple Developer account, free tier works)
4.  Let Xcode manage signing automatically

### 3\. Use with agent-browser

    # Connect device via USB, then use the UDID
    agent-browser -p ios --device "<DEVICE_UDID>" open https://example.com
    
    # Or use the device name if unique
    agent-browser -p ios --device "John's iPhone" open https://example.com

### Real device notes

*   First run installs WebDriverAgent to the device (may require Trust prompt on device)
*   Device must be unlocked and connected via USB
*   Slightly slower initial connection than simulator
*   Tests against real Safari performance and behavior
*   On first install, go to Settings → General → VPN & Device Management to trust the developer certificate

Performance notes
-----------------

*   **First launch:** Takes 30-60 seconds to boot the simulator and start Appium
*   **Subsequent commands:** Fast (simulator stays running)
*   **Close command:** Shuts down simulator and Appium server

Differences from desktop
------------------------

| Feature | Desktop | iOS |
| --- | --- | --- |
| Browser | Chrome, Lightpanda | Safari only |
| Tabs | Supported | Single tab only |
| PDF export | Supported | Not supported |
| Screencast | Supported | Not supported |
| Swipe gestures | Not native | Native support |

Troubleshooting
---------------

### Appium not found

    # Make sure Appium is installed globally
    npm install -g appium
    appium driver install xcuitest
    
    # Verify installation
    appium --version

### No simulators available

Open Xcode and download iOS Simulator runtimes from **Settings → Platforms**.

### Simulator won't boot

Try booting the simulator manually from Xcode or the Simulator app to ensure it works, then retry with agent-browser.

Ask AI⌘I

---

# Security | agent-browser

Security

Copy Page

Security
========

agent-browser includes security features to protect against credential exposure, prompt injection via untrusted page content, and unauthorized browser actions.

All security features are opt-in. By default, agent-browser imposes no restrictions on navigation, actions, or output. Enable these features as needed for your deployment -- existing workflows are unaffected until you explicitly activate a feature.

Threat Model
------------

These features are designed to mitigate the following threats when an LLM-based agent drives a browser:

*   **Credential exposure** -- Passwords stored in the auth vault are never included in LLM context. The CLI handles vault operations locally; credentials do not pass through the daemon's IPC channel.
*   **Prompt injection via page content** -- Malicious pages can embed text that looks like tool output or system instructions. Content boundary markers (`--content-boundaries`) let the orchestrator distinguish trusted tool output from untrusted page content.
*   **Unauthorized navigation / data exfiltration** -- A compromised or manipulated agent could navigate to attacker-controlled domains to exfiltrate data. The domain allowlist (`--allowed-domains`) blocks navigations, sub-resource requests, WebSocket connections, EventSource streams, and `sendBeacon` calls to non-allowed domains.
*   **Unauthorized destructive actions** -- Action policy (`--action-policy`) and confirmation gating (`--confirm-actions`) prevent the agent from performing dangerous operations (eval, downloads, uploads) without explicit approval.
*   **Context flooding** -- Large page outputs can overwhelm an LLM's context window. Output truncation (`--max-output`) caps the size of page-sourced content.

### Known limitations

*   **WebSocket/EventSource blocking is best-effort.** It works by overriding browser constructors via an init script. If the `eval` action category is allowed, page scripts could theoretically restore the original constructors. Deny `eval` via `--action-policy` for maximum protection.
*   **Domain filter timing on remote connections.** When connecting to a pre-existing browser via CDP or a cloud provider, pages may have already loaded content before the domain filter is installed. agent-browser navigates disallowed pages to `about:blank` after the filter is active, but resources loaded before that point are not retroactively blocked.
*   **Content boundaries are defense-in-depth.** They rely on the LLM and orchestrator respecting the structural markers. A sufficiently capable adversarial page could attempt to mimic the boundary format, though the per-process CSPRNG nonce makes this impractical to predict.
*   **Confirmation timeout.** Pending confirmations auto-deny after 60 seconds. Orchestrators must respond within that window.
*   **Non-TTY auto-deny.** When `--confirm-interactive` is set but stdin is not a terminal (e.g., piped input), actions are automatically denied to prevent accidental approval in non-interactive contexts.

Authentication Vault
--------------------

Store credentials locally and reference them by name. The LLM never sees passwords.

    # Save credentials (encrypted if AGENT_BROWSER_ENCRYPTION_KEY is set)
    # Recommended: pipe password via stdin to avoid shell history / process listing exposure
    echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
    
    # Or pass directly (a warning will be shown)
    agent-browser auth save github --url https://github.com/login --username user --password pass
    
    # Login using saved credentials
    agent-browser auth login github
    
    # List saved profiles (names and URLs only, no secrets)
    agent-browser auth list
    
    # Show profile metadata
    agent-browser auth show github
    
    # Delete a profile
    agent-browser auth delete github

`auth login` navigates with the `load` lifecycle event and then waits for form selectors to appear before filling/clicking. This makes delayed SPA login pages more reliable while avoiding `networkidle` hangs on pages with long-lived background requests.

Custom selectors can be specified if auto-detection fails:

    agent-browser auth save myapp \
      --url https://app.example.com/login \
      --username user --password pass \
      --username-selector "#email" \
      --password-selector "#password" \
      --submit-selector "button.login"

Profiles are stored in `~/.agent-browser/auth/` and always encrypted with AES-256-GCM. If `AGENT_BROWSER_ENCRYPTION_KEY` is not set, a key is auto-generated at `~/.agent-browser/.encryption-key` on first use. Back up this file or set the environment variable explicitly for portability.

File permissions are enforced on both Unix (`chmod 600`/`700`) and Windows (`icacls` restricted to the current user) to prevent other users from reading encryption keys or auth profiles.

Content Boundary Markers
------------------------

When `--content-boundaries` is enabled, all page-sourced output is wrapped in structural markers so LLMs can distinguish tool output from untrusted page content:

    --- AGENT_BROWSER_PAGE_CONTENT nonce=a1b2c3d4 origin=https://example.com ---
    [snapshot / text / html / eval output here]
    --- END_AGENT_BROWSER_PAGE_CONTENT nonce=a1b2c3d4 ---

The nonce is a random value generated per CLI process invocation, making it unpredictable to page content that might attempt to spoof the boundary.

Enable via flag or environment variable:

    agent-browser --content-boundaries snapshot
    # or
    export AGENT_BROWSER_CONTENT_BOUNDARIES=1

Affected output types: `snapshot`, `get text`, `get html`, `eval`, `console`.

In `--json` mode, boundary metadata is injected into the JSON response as a `_boundary` object containing `nonce` and `origin` fields, allowing orchestrators to verify provenance programmatically:

    {
      "success": true,
      "data": { "snapshot": "...", "origin": "https://example.com" },
      "_boundary": { "nonce": "a1b2c3d4e5f6...", "origin": "https://example.com" }
    }

Domain Allowlist
----------------

Restrict which domains the browser can interact with, preventing redirect-based attacks and data exfiltration:

    agent-browser --allowed-domains "example.com,*.example.com,github.com" open https://example.com
    # or
    export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com"

Supports exact match (`github.com`) and wildcard prefix (`*.example.com`, which also matches the bare domain `example.com`). Both page navigations and sub-resource requests (scripts, images, fetch, XHR, etc.) to non-allowed domains are blocked, preventing data exfiltration. WebSocket and EventSource connections are also blocked via constructor-level patching. Non-http(s) sub-resources (data URIs, blobs) are still allowed. When a request is blocked, the command returns an error.

> **Note:** The WebSocket/EventSource blocking is best-effort -- it works by overriding the browser constructors via an init script. If the `eval` action category is allowed, page scripts could theoretically restore the original constructors. For maximum protection, deny the `eval` category via `--action-policy` when using `--allowed-domains`.

Config file:

    {
      "allowedDomains": ["example.com", "*.example.com", "github.com"]
    }

> **CDN and third-party resources:** The domain filter blocks all sub-resource requests (scripts, stylesheets, images, fonts, fetch/XHR) to non-allowed domains. Most websites load assets from CDN domains. Include these in your allowlist or pages will break. For example:
> 
>     --allowed-domains "myapp.com,*.myapp.com,cdn.jsdelivr.net,fonts.googleapis.com,fonts.gstatic.com"

Action Policy
-------------

Gate actions using a static policy file. The policy is enforced by the daemon -- denied actions fail immediately.

    agent-browser --action-policy ./policy.json open https://example.com
    # or
    export AGENT_BROWSER_ACTION_POLICY=./policy.json

Example policy (permissive with specific denials):

    {
      "default": "allow",
      "deny": ["eval", "download", "upload"]
    }

Example policy (restrictive):

    {
      "default": "deny",
      "allow": ["navigate", "snapshot", "click", "scroll", "wait", "get"]
    }

| Category | Actions |
| --- | --- |
| `navigate` | open, back, forward, reload, tab new |
| `click` | click, dblclick, tap |
| `fill` | fill, type, keyboard type/inserttext, select, check, uncheck |
| `eval` | eval, evalhandle, addscript, addinitscript, addstyle, expose, setcontent |
| `download` | download, waitfordownload |
| `upload` | upload |
| `snapshot` | snapshot, screenshot, pdf, diff |
| `scroll` | scroll, scrollintoview |
| `wait` | wait, waitforurl, waitforloadstate, waitforfunction |
| `get` | get text/html/url/title, count, isvisible, getbyrole, getbytext, getbylabel, etc. |
| `interact` | hover, focus, drag, press, keydown, keyup, mousemove, dispatch |
| `network` | network route/unroute, requests, har start/stop |
| `state` | state save/load, cookies set, storage set |

Auth vault operations (`auth save`, `auth login`, `auth list`, `auth show`, `auth delete`) and other internal/meta operations bypass action policy enforcement since they are trusted local operations. Domain allowlist restrictions still apply to `auth login` navigations.

Action Confirmation
-------------------

For actions that require explicit approval, use `--confirm-actions` to specify categories that require confirmation:

    # Orchestrator mode: returns confirmation_required response
    agent-browser --confirm-actions eval,download eval "document.title"
    
    # Then approve or deny:
    agent-browser confirm c_8f3a1234
    agent-browser deny c_8f3a1234

For interactive (human-in-the-loop) confirmation:

    agent-browser --confirm-actions eval,download --confirm-interactive eval "document.title"
    # Prompts: Allow? [y/N]

Pending confirmations auto-deny after 60 seconds.

> **Non-TTY behavior:** When `--confirm-interactive` is set but stdin is not a TTY (e.g., piped input or running inside an automated pipeline), actions are automatically denied. This prevents accidental approval in non-interactive contexts.

Output Length Limits
--------------------

Prevent context flooding by truncating large page outputs:

    agent-browser --max-output 50000 get text body
    # or
    export AGENT_BROWSER_MAX_OUTPUT=50000

Affected output types: `snapshot`, `get text`, `get html`, `eval`, `console`.

Environment Variables
---------------------

| Variable | Description |
| --- | --- |
| `AGENT_BROWSER_CONTENT_BOUNDARIES` | Wrap page output in boundary markers |
| `AGENT_BROWSER_MAX_OUTPUT` | Max characters for page output |
| `AGENT_BROWSER_ALLOWED_DOMAINS` | Comma-separated allowed domain patterns |
| `AGENT_BROWSER_ACTION_POLICY` | Path to action policy JSON file |
| `AGENT_BROWSER_CONFIRM_ACTIONS` | Comma-separated action categories requiring confirmation |
| `AGENT_BROWSER_CONFIRM_INTERACTIVE` | Enable interactive confirmation prompts |
| `AGENT_BROWSER_ENCRYPTION_KEY` | 64-char hex key for AES-256-GCM encryption (auth vault + sessions) |

Recommended Configuration
-------------------------

For production AI agent deployments:

    {
      "contentBoundaries": true,
      "maxOutput": 50000,
      "allowedDomains": ["your-app.com", "*.your-app.com"],
      "actionPolicy": "./policy.json"
    }

Ask AI⌘I

---

# Browser Use | agent-browser

Browser Use

Copy Page

Browser Use
===========

[Browser Use](https://browser-use.com/)
 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.).

Setup
-----

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

Or use environment variables for CI/scripts:

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

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

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](https://cloud.browser-use.com/settings?tab=api-keys)
. Free credits are available to get started, with pay-as-you-go pricing after.

Ask AI⌘I

---

# Browserless | agent-browser

Browserless

Copy Page

Browserless
===========

[Browserless](https://browserless.io/)
 provides cloud browser infrastructure with a Sessions API. Use it when running agent-browser in environments where a local browser isn't available.

Setup
-----

    export BROWSERLESS_API_KEY="your-api-token"
    agent-browser -p browserless open https://example.com

Or use environment variables for CI/scripts:

    export AGENT_BROWSER_PROVIDER=browserless
    export BROWSERLESS_API_KEY="your-api-token"
    agent-browser open https://example.com

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

Configuration
-------------

| Variable | Description | Default |
| --- | --- | --- |
| `BROWSERLESS_API_KEY` | API token (required) |     |
| `BROWSERLESS_API_URL` | Base API URL (for custom regions or self-hosted) | `https://production-sfo.browserless.io` |
| `BROWSERLESS_BROWSER_TYPE` | Type of browser to use (`chromium` or `chrome`) | `chromium` |
| `BROWSERLESS_TTL` | Session TTL in milliseconds | `300000` |
| `BROWSERLESS_STEALTH` | Enable stealth mode | `true` |

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

Get your API token from the [Browserless Dashboard](https://browserless.io/)
.

Ask AI⌘I

---

# Browserbase | agent-browser

Browserbase

Copy Page

Browserbase
===========

[Browserbase](https://browserbase.com/)
 provides remote browser infrastructure to make deployment of agentic browsing agents easy. Use it when running agent-browser in environments where a local browser isn't feasible.

Setup
-----

    export BROWSERBASE_API_KEY="your-api-key"
    agent-browser -p browserbase open https://example.com

Or use environment variables for CI/scripts:

    export AGENT_BROWSER_PROVIDER=browserbase
    export BROWSERBASE_API_KEY="your-api-key"
    agent-browser open https://example.com

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

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

Get your API key from the [Browserbase Dashboard](https://browserbase.com/overview)
.

Ask AI⌘I

---

# Kernel | agent-browser

Kernel

Copy Page

Kernel
======

[Kernel](https://www.kernel.sh/)
 provides cloud browser infrastructure for AI agents with features like stealth mode and persistent profiles.

Setup
-----

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

Or use environment variables for CI/scripts:

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

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

Configuration
-------------

| Variable | Description | Default |
| --- | --- | --- |
| `KERNEL_API_KEY` | API key (required) |     |
| `KERNEL_HEADLESS` | Run browser in headless mode | `true` |
| `KERNEL_STEALTH` | Enable stealth mode to avoid bot detection | `false` |
| `KERNEL_TIMEOUT_SECONDS` | Session timeout in seconds | `300` |
| `KERNEL_PROFILE_NAME` | Browser profile name for persistent cookies/logins | (none) |

**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.

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

Get your API key from the [Kernel Dashboard](https://dashboard.onkernel.com/)
.

Ask AI⌘I

---

# AgentCore | agent-browser

AgentCore

Copy Page

AgentCore
=========

[AWS Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/)
 provides cloud browser sessions with SigV4 authentication. Use it when running agent-browser in AWS environments or when you need managed cloud browsers backed by AWS infrastructure.

Setup
-----

Credentials are automatically resolved from:

1.  Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
2.  AWS CLI (`aws configure export-credentials`) which supports SSO, profiles, IAM roles, etc.

    agent-browser -p agentcore open https://example.com

Or use environment variables for CI/scripts:

    export AGENT_BROWSER_PROVIDER=agentcore
    agent-browser open https://example.com

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

Configuration
-------------

| Variable | Description | Default |
| --- | --- | --- |
| `AGENTCORE_REGION` | AWS region for the AgentCore endpoint | `us-east-1` |
| `AGENTCORE_BROWSER_ID` | Browser identifier | `aws.browser.v1` |
| `AGENTCORE_PROFILE_ID` | Browser profile for persistent state (cookies, localStorage) | (none) |
| `AGENTCORE_SESSION_TIMEOUT` | Session timeout in seconds | `3600` |
| `AWS_PROFILE` | AWS CLI profile for credential resolution | `default` |
| `AWS_ACCESS_KEY_ID` | AWS access key (checked before AWS CLI fallback) | (none) |
| `AWS_SECRET_ACCESS_KEY` | AWS secret key | (none) |
| `AWS_SESSION_TOKEN` | Temporary session token (for STS/SSO credentials) | (none) |

Browser Profiles
----------------

Use `AGENTCORE_PROFILE_ID` to persist browser state (cookies, localStorage) across sessions:

    AGENTCORE_PROFILE_ID=my-profile agent-browser -p agentcore open https://example.com

When a profile is set, AgentCore stores and restores browser state automatically between sessions.

Live View
---------

When a session starts, AgentCore prints a Live View URL to stderr:

    Session: abc123-def456
    Live View: https://us-east-1.console.aws.amazon.com/bedrock-agentcore/browser/aws.browser.v1/session/abc123-def456#

Open this URL in your browser to watch the agent session in real time from the AWS Console.

Credential Resolution
---------------------

AgentCore uses lightweight manual SigV4 signing (no AWS SDK dependency). Credentials are resolved in order:

1.  **Environment variables** (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`, optionally `AWS_SESSION_TOKEN`)
2.  **AWS CLI** (`aws configure export-credentials --format env`), which supports SSO, IAM roles, credential files, and profiles

If using SSO, run `aws sso login` before launching agent-browser. Set `AWS_PROFILE` to select a specific named profile.

Example
-------

    # Basic usage (credentials auto-resolved via AWS CLI)
    agent-browser -p agentcore open https://example.com
    
    # With a browser profile for persistent login state
    AGENTCORE_PROFILE_ID=my-profile agent-browser -p agentcore open https://x.com/home
    
    # With explicit region
    AGENTCORE_REGION=eu-west-1 agent-browser -p agentcore open https://example.com
    
    # With SSO profile
    AWS_PROFILE=my-sso-profile agent-browser -p agentcore open https://example.com

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

Ask AI⌘I

---

# Native Mode | agent-browser

Native Mode

Copy Page

Native Mode
===========

agent-browser is now 100% native Rust by default. The Node.js/Playwright daemon has been removed.

This page is no longer relevant. See the main [documentation](https://agent-browser.dev/)
 for current architecture and usage.

Ask AI⌘I

---

# Chrome | agent-browser

Chrome

Copy Page

Chrome
======

Chrome (and Chromium) is the default browser engine. agent-browser discovers, launches, and manages the Chrome process automatically via the Chrome DevTools Protocol (CDP).

Binary Discovery
----------------

When no `--executable-path` is provided, agent-browser searches for Chrome in this order:

| Platform | Locations checked |
| --- | --- |
| macOS | `/Applications/Google Chrome.app`, `/Applications/Google Chrome Canary.app`, `/Applications/Chromium.app`, `/Applications/Brave Browser.app`, Puppeteer cache (`~/.cache/puppeteer/chrome/` or `PUPPETEER_CACHE_DIR`), Chrome for Testing cache |
| Linux | `google-chrome`, `google-chrome-stable`, `chromium-browser`, `chromium` in PATH, Puppeteer cache (`~/.cache/puppeteer/chrome/` or `PUPPETEER_CACHE_DIR`), Chrome for Testing cache |
| Windows | `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe`, `C:\Program Files\Google\Chrome\Application\chrome.exe`, `C:\Program Files (x86)...\chrome.exe` |

If Chrome is not found, run `agent-browser install` to download Chrome from Chrome for Testing.

Usage
-----

Chrome is the default engine -- no `--engine` flag is needed:

    agent-browser open example.com

To be explicit:

    agent-browser --engine chrome open example.com

Custom Binary
-------------

Point to any Chromium-based browser with `--executable-path`:

    agent-browser --executable-path /path/to/chromium open example.com

Or via environment variable:

    export AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium
    agent-browser open example.com

Chrome-Specific Features
------------------------

These features are available only with Chrome:

| Feature | Flag |
| --- | --- |
| Browser extensions | `--extension <path>` |
| Persistent profiles | `--profile <path>` (sets Chrome's `--user-data-dir`) |
| Storage state | `--state <path>` |
| File URL access | `--allow-file-access` |
| Headed mode | `--headed` |
| Custom launch args | `--args <args>` |

Containers and CI
-----------------

In Docker, CI runners, or other sandboxed environments, Chrome's user namespace sandbox may need to be disabled:

    agent-browser --args "--no-sandbox" open example.com

agent-browser automatically adds `--no-sandbox` when it detects a container environment (Docker, Podman, running as root).

Ask AI⌘I

---

# Lightpanda | agent-browser

Lightpanda

Copy Page

Lightpanda
==========

[Lightpanda](https://lightpanda.io/)
 is a headless browser engine built from scratch in Zig for machines. It starts instantly, uses 10x less memory than Chrome, and executes 10x faster.

agent-browser manages Lightpanda the same way it manages Chrome -- spawning the process, connecting via CDP, and shutting it down. All downstream commands (snapshot, click, fill, screenshot, etc.) work through the same CDP protocol path.

Installation
------------

Install the Lightpanda binary before using it with agent-browser:

| Platform | Command |
| --- | --- |
| macOS (Apple Silicon) | `curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos && chmod a+x ./lightpanda` |
| Linux (x86\_64) | `curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && chmod a+x ./lightpanda` |

Move the binary somewhere in your `PATH` (e.g. `/usr/local/bin/lightpanda` or `~/.local/bin/lightpanda`).

See the [Lightpanda installation docs](https://lightpanda.io/docs/open-source/installation)
 for more options.

Usage
-----

Use the `--engine` flag to select Lightpanda:

    agent-browser --engine lightpanda open example.com
    agent-browser --engine lightpanda snapshot
    agent-browser --engine lightpanda screenshot

Or set it as the default via environment variable:

    export AGENT_BROWSER_ENGINE=lightpanda
    agent-browser open example.com

Or in your `agent-browser.json` config:

    {
      "engine": "lightpanda"
    }

Custom Binary Path
------------------

If the `lightpanda` binary is not in your `PATH`, use `--executable-path`:

    agent-browser --engine lightpanda --executable-path /path/to/lightpanda open example.com

Differences from Chrome
-----------------------

Lightpanda is a purpose-built headless engine. Some Chrome-specific features are not available:

| Feature | Status |
| --- | --- |
| Extensions (`--extension`) | Not supported |
| Persistent profiles (`--profile`) | Not supported |
| Storage state (`--state`) | Not supported |
| File access (`--allow-file-access`) | Not supported |
| Headed mode (`--headed`) | Not applicable (headless only) |
| Screenshots | Depends on Lightpanda CDP support |

agent-browser returns a clear error if you combine `--engine lightpanda` with unsupported flags.

When to Use Lightpanda
----------------------

Lightpanda is a good fit for:

*   Fast web scraping and data extraction
*   AI agent workflows where speed and low memory matter
*   CI/CD environments with constrained resources
*   High-volume parallel automation

Use Chrome when you need full browser fidelity, extensions, or persistent profiles.

Ask AI⌘I

---

# Streaming | agent-browser

Streaming

Copy Page

Streaming
=========

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

Streaming
---------

Every session automatically starts a WebSocket stream server on an OS-assigned port. The server streams viewport frames and accepts input events (mouse, keyboard, touch).

To bind to a specific port, set `AGENT_BROWSER_STREAM_PORT`:

    AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com

You can also manage streaming at runtime:

    agent-browser stream status            # Show streaming state and bound port
    agent-browser stream enable --port 9223  # Re-enable on a specific port
    agent-browser stream disable           # Stop streaming for the session

`stream status` returns the enabled state, active port, browser connection state, and whether screencasting is active. `stream disable` tears the server down and removes the session's `.stream` metadata file.

Runtime status response
-----------------------

`agent-browser stream status --json` returns data like:

    {
      "enabled": true,
      "port": 9223,
      "connected": true,
      "screencasting": true
    }

`connected` reports whether the daemon currently has a browser attached. `screencasting` reports whether frames are actively being produced for the stream server.

Relationship to screencast commands
-----------------------------------

`stream enable` creates the WebSocket server and keeps it available for the session. WebSocket clients then trigger live frame delivery automatically.

The lower-level `screencast_start` and `screencast_stop` commands still control explicit CDP screencasts directly. Use them when you want a screencast without the WebSocket runtime server.

WebSocket protocol
------------------

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

### Frame messages

The server sends frame messages with base64-encoded images:

    {
      "type": "frame",
      "data": "<base64-encoded-jpeg>",
      "metadata": {
        "deviceWidth": 1280,
        "deviceHeight": 720,
        "pageScaleFactor": 1,
        "offsetTop": 0,
        "scrollOffsetX": 0,
        "scrollOffsetY": 0
      }
    }

### Status messages

Connection and screencast status:

    {
      "type": "status",
      "connected": true,
      "screencasting": true,
      "viewportWidth": 1280,
      "viewportHeight": 720
    }

Input injection
---------------

Send input events to control the browser remotely.

### Mouse events

    // Click
    {
      "type": "input_mouse",
      "eventType": "mousePressed",
      "x": 100,
      "y": 200,
      "button": "left",
      "clickCount": 1
    }
    
    // Release
    {
      "type": "input_mouse",
      "eventType": "mouseReleased",
      "x": 100,
      "y": 200,
      "button": "left"
    }
    
    // Move
    {
      "type": "input_mouse",
      "eventType": "mouseMoved",
      "x": 150,
      "y": 250
    }
    
    // Scroll
    {
      "type": "input_mouse",
      "eventType": "mouseWheel",
      "x": 100,
      "y": 200,
      "deltaX": 0,
      "deltaY": 100
    }

### Keyboard events

    // Key down
    {
      "type": "input_keyboard",
      "eventType": "keyDown",
      "key": "Enter",
      "code": "Enter"
    }
    
    // Key up
    {
      "type": "input_keyboard",
      "eventType": "keyUp",
      "key": "Enter",
      "code": "Enter"
    }
    
    // Type character
    {
      "type": "input_keyboard",
      "eventType": "char",
      "text": "a"
    }
    
    // With modifiers (1=Alt, 2=Ctrl, 4=Meta, 8=Shift)
    {
      "type": "input_keyboard",
      "eventType": "keyDown",
      "key": "c",
      "code": "KeyC",
      "modifiers": 2
    }

### Touch events

    // Touch start
    {
      "type": "input_touch",
      "eventType": "touchStart",
      "touchPoints": [{ "x": 100, "y": 200 }]
    }
    
    // Touch move
    {
      "type": "input_touch",
      "eventType": "touchMove",
      "touchPoints": [{ "x": 150, "y": 250 }]
    }
    
    // Touch end
    {
      "type": "input_touch",
      "eventType": "touchEnd",
      "touchPoints": []
    }
    
    // Multi-touch (pinch zoom)
    {
      "type": "input_touch",
      "eventType": "touchStart",
      "touchPoints": [\
        { "x": 100, "y": 200, "id": 0 },\
        { "x": 200, "y": 200, "id": 1 }\
      ]
    }

Programmatic API
----------------

For advanced use, control streaming directly via the TypeScript API:

    import { BrowserManager } from 'agent-browser';
    
    const browser = new BrowserManager();
    await browser.launch({ headless: true });
    await browser.navigate('https://example.com');
    
    // Start screencast with callback
    await browser.startScreencast((frame) => {
      console.log('Frame:', frame.metadata.deviceWidth, 'x', frame.metadata.deviceHeight);
      // frame.data is base64-encoded image
    }, {
      format: 'jpeg',  // or 'png'
      quality: 80,     // 0-100, jpeg only
      maxWidth: 1280,
      maxHeight: 720,
      everyNthFrame: 1
    });
    
    // Inject mouse event
    await browser.injectMouseEvent({
      type: 'mousePressed',
      x: 100,
      y: 200,
      button: 'left',
      clickCount: 1
    });
    
    // Inject keyboard event
    await browser.injectKeyboardEvent({
      type: 'keyDown',
      key: 'Enter',
      code: 'Enter'
    });
    
    // Inject touch event
    await browser.injectTouchEvent({
      type: 'touchStart',
      touchPoints: [{ x: 100, y: 200 }]
    });
    
    // Check if screencasting
    console.log('Active:', browser.isScreencasting());
    
    // Stop screencast
    await browser.stopScreencast();

Use cases
---------

*   **Pair browsing** - Human watches and assists AI agent in real-time
*   **Remote preview** - View browser output in a separate UI
*   **Recording** - Capture frames for video generation
*   **Mobile testing** - Inject touch events for mobile emulation
*   **Accessibility testing** - Manual interaction during automated tests

Ask AI⌘I

---

# Changelog | agent-browser

Changelog

Copy Page

Changelog
=========

v0.24.0
-------

April 2, 2026

### New Features

*   **AWS Bedrock AgentCore provider** - Added AWS Bedrock AgentCore as a cloud browser provider. Connect with `--provider agentcore` or `AGENT_BROWSER_PROVIDER=agentcore`. Uses lightweight manual SigV4 signing for authentication with support for the full AWS credential provider chain (environment variables, AWS CLI, SSO, IAM roles). Configure with `AGENTCORE_REGION`, `AGENTCORE_PROFILE_ID`, and `AGENTCORE_BROWSER_ID` environment variables. Returns session ID and Live View URL in the launch response (#397)

### Documentation

*   Added AgentCore provider page to docs site, README options table, SKILL.md, and dashboard provider icons (#1120)

* * *

v0.23.4
-------

March 31, 2026

### Bug Fixes

*   Fixed **daemon hang on Linux** caused by a `waitpid(-1)` race condition in the SIGCHLD handler that stole exit statuses from Rust's `Child` handles, leaving the daemon in a broken state. Replaced the global signal handler with targeted crash detection via the existing drain interval (#1098)

* * *

v0.23.3
-------

March 30, 2026

### Bug Fixes

*   Fixed **drag and drop** not working because `mouseMoved` events during the drag omitted the `buttons` bitmask, causing the browser to see `event.buttons === 0` and never fire `dragstart`/`dragover`/`drop` (#1087)

* * *

v0.23.2
-------

March 30, 2026

### New Features

*   **Dashboard session creation** - Sessions can now be created directly from the dashboard UI. A new session dialog provides a unified selector grid for local engines (Chrome, Lightpanda) and cloud providers (Browserbase, Browserless, Browser Use, Kernel) with async creation, loading state, and error display (#1092)
*   **Dashboard provider icons** - The session sidebar now shows the provider or engine icon for each session, making it easy to identify which backend a session is using (#1092)

### Bug Fixes

*   Fixed **Browser Use** provider using an intermediate API call instead of connecting directly via WSS, which caused connection failures (#1092)
*   Fixed **Browserbase** provider not sending an explicit JSON body and `Content-Type` header, causing session creation to fail (#1092)
*   Fixed **provider navigation** hanging because `wait_for_lifecycle` waited for page load events that remote providers may not emit. Navigation with `--provider` now automatically sets `waitUntil=none` (#1092)
*   Fixed **remote CDP connections** timing out by increasing the CDP connect timeout from 10s to 25s for cloud providers (#1092)
*   Fixed **zombie daemon processes** not being cleaned up when a provider connection fails during session creation from the dashboard (#1092)

* * *

v0.23.1
-------

March 30, 2026

### New Features

*   **Auto-dismissal for alert and beforeunload dialogs** - JavaScript `alert()` and `beforeunload` dialogs are now automatically accepted to prevent the agent from blocking indefinitely. `confirm` and `prompt` dialogs still require explicit `dialog accept/dismiss` commands. Disable with `--no-auto-dialog` flag or `AGENT_BROWSER_NO_AUTO_DIALOG` environment variable (#1075)
*   **Puppeteer browser cache fallback** - Chrome discovery now searches `~/.cache/puppeteer/chrome/` (or `PUPPETEER_CACHE_DIR`) for Chrome binaries, so users with an existing Puppeteer installation can use agent-browser without a separate install step (#1088)
*   **Console output improvements** - `console.log` of objects now shows the actual object preview (e.g. `{userId: "abc", count: 42}`) instead of `"Object"`. JSON output includes a raw `args` array for programmatic access (#1040)

### Bug Fixes

*   Fixed **same-document navigation** (e.g. SPA hash routing) hanging forever because `wait_for_lifecycle` waited for a `Page.loadEventFired` that never fires on same-document navigations (#1059)
*   Fixed **save\_state** only capturing cookies and localStorage for the current origin, silently dropping cross-domain data (e.g. SSO/CAS auth cookies). Now uses `Network.getAllCookies` and collects localStorage from all visited origins (#1064)
*   Fixed **externally opened tabs** not appearing in `tab list` when using `--cdp` mode. Tabs opened by the user or another CDP client are now detected and tracked (#1042)
*   Fixed **dashboard server** not picking up installed files without a restart. `dashboard install` now takes effect immediately on a running server (#1066)
*   Fixed **Windows Chrome extraction** failing because zip path normalization used forward slashes while the extraction code expected backslashes (#1088)

* * *

v0.23.0
-------

March 27, 2026

### New Features

*   **Observability dashboard** - Added a local web UI (`dashboard`) that shows live browser viewports, command activity feeds, console output, network requests, storage, and extensions for all sessions. Manage it with `dashboard start`, `dashboard stop`, and `dashboard install`. The dashboard runs as a standalone background process and all sessions stream to it automatically (#1034)

    agent-browser dashboard install
    agent-browser dashboard start
    agent-browser open example.com    # session appears in dashboard
    agent-browser dashboard stop

*   **Runtime stream management** - Added `stream enable`, `stream disable`, and `stream status` commands to control WebSocket streaming at runtime. Streaming is now always enabled by default; `AGENT_BROWSER_STREAM_PORT` overrides the port instead of toggling the feature (#951)
*   **Close all sessions** - Added `close --all` flag to close every active browser session at once

### Bug Fixes

*   Fixed **Lightpanda engine** compatibility (#1050)
*   Fixed **Windows daemon TCP bind** failing when Hyper-V reserves the port by falling back to an OS-assigned port and writing it to a `.port` file (#1041)
*   Fixed **Windows dashboard relay** using Unix socket instead of TCP (#1038)
*   Fixed **radio/checkbox elements** being dropped from compact snapshot tree because the `ref=` check required a leading `[` that those elements lack (#1008)\
\
* * *\
\
v0.22.3\
-------\
\
March 25, 2026\
\
### Bug Fixes\
\
*   **Re-apply download behavior on recording context** - Fixed an issue where downloads were silently dropped in recording contexts because `Browser.setDownloadBehavior` set at launch only applied to the default context. The download behavior is now re-applied when a new recording context is created (#1019)\
*   **Reap zombie Chrome process and fast-detect crash for auto-restart** - Added a non-blocking process-exit check before attempting CDP connection checks. This prevents a 3-second CDP timeout when Chrome has already crashed or exited, enabling faster detection and auto-restart of the browser (#1023)\
*   **Route keyboard `type` through text input** - Fixed keyboard `type` subaction to correctly route through the text input handler, and added support for an `insertText` subaction using `Input.insertText` (#1014)\
*   **Handle `--clear` flag in `console` command** - Fixed the `console` command to accept and process a `clear` parameter, allowing console event history to be cleared (#1015)\
\
* * *\
\
v0.22.2\
-------\
\
March 24, 2026\
\
### New Features\
\
*   **Dialog status command** - Added `dialog status` command to check whether a JavaScript dialog is currently open (#999)\
*   **Dialog warning field** - Command responses now include a `warning` field when a JavaScript dialog is pending, indicating the dialog type and message (#999)\
\
### Improvements\
\
*   **Standard proxy environment variables** - The proxy setting now automatically falls back to standard environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and their lowercase variants), with `NO_PROXY`/`no_proxy` respected for bypass rules (#1000)\
*   **Font packages for `--with-deps`** - Installing with `--with-deps` now includes CJK and emoji font packages on Linux (Debian, RPM, and yum-based distros) to prevent missing glyphs when rendering international content (#1002)\
\
### Bug Fixes\
\
*   Fixed `state show` always failing with "Missing 'path' parameter" due to a mismatched JSON field name (#994)\
*   Fixed `console` command returning only `Done` due to a JSON field name mismatch in the response (#986)\
*   Fixed browser-domain CDP events being dropped during downloads due to a `sessionId` mismatch (#998)\
*   Fixed proxy authentication by handling credentials via the CDP `Fetch.authRequired` event rather than passing them inline (#1000)\
\
* * *\
\
v0.22.1\
-------\
\
March 24, 2026\
\
### Bug Fixes\
\
*   Fixed **modifier key chords** (e.g. `Control+a`, `Shift+Enter`, `Control+Shift+a`) not being handled correctly when using `press`. Modifier keys are now parsed and forwarded as CDP modifier bitmasks rather than treated as part of the key name (#980)\
*   Fixed **query parameters being dropped** from `--cdp` HTTP URLs (e.g. `http://host:9222?mode=Hello`). Query strings are now preserved and forwarded to the remote CDP endpoint (#982)\
\
* * *\
\
v0.22.0\
-------\
\
March 23, 2026\
\
### New Features\
\
*   **Cross-origin iframe support** - Added support for snapshots and interactions within cross-origin iframes via `Target.setAutoAttach` (#949)\
*   **Network request detail and filtering** - Added `network request <requestId>` command to view full request/response detail, and new filtering options for `network requests` including `--type` (e.g. `xhr,fetch`), `--method` (e.g. `POST`), and `--status` (e.g. `2xx`, `400-499`) (#935)\
\
    agent-browser network requests --type xhr,fetch --method POST\
    agent-browser network request <requestId>\
\
### Improvements\
\
*   **Snapshot usability** - Reduced AI cognitive load by filtering semantic noise from snapshot output; cursor-interactive elements are now included by default, making the `-C` flag unnecessary (#968)\
*   **Upgrade command** - Improved robustness of installation method detection in the upgrade command (#960)\
*   **Target tracking** - Enhanced target tracking and page information handling for more reliable browser session management (#969)\
\
### Bug Fixes\
\
*   Fixed **viewport dimensions** being reported incorrectly in streaming status messages and screencast (#952)\
*   Fixed **`find` command** flags such as `--exact` and `--name` leaking into fill values when used with fill actions (#955)\
*   Fixed **state commands** incorrectly starting the daemon when no `session_name` is provided (#677, #964)\
*   Fixed **auto-connect** triggering when the daemon is already running, preventing duplicate connections (#971)\
*   Fixed **Enter key press** not working by adding a text field to `keyDown` events (#972)\
*   Fixed **download command** to properly handle absolute paths and correctly click target elements (#970)\
\
### Breaking Changes\
\
*   The `-C` / `--cursor` flag for `snapshot` is deprecated; cursor-interactive elements are now included by default and the flag has no additional effect (#968)\
\
* * *\
\
v0.21.4\
-------\
\
March 20, 2026\
\
### Bug Fixes\
\
*   **Auth login readiness** - `agent-browser auth login` now navigates with `load`, waits for usable login form selectors, and uses staged username detection (targeted email/username selectors first, then broad text-input fallback). This reduces SPA timing failures, avoids false matches on unrelated text fields, and prevents `networkidle` hangs on pages with continuous background requests.\
\
* * *\
\
v0.21.3\
-------\
\
March 20, 2026\
\
### Bug Fixes\
\
*   **WebSocket keepalive for remote browsers** - Added WebSocket Ping frames and TCP `SO_KEEPALIVE` to prevent CDP connections from being silently dropped by intermediate proxies during idle periods (#936)\
*   **XPath selector support** - Fixed element resolution to correctly handle the `xpath=` selector prefix (#908)\
\
### Performance\
\
*   **Fast-path for identical snapshots** - Short-circuits the Myers diff algorithm when comparing a snapshot to itself, avoiding unnecessary computation in retry and loop workloads (#922)\
\
* * *\
\
v0.21.2\
-------\
\
March 18, 2026\
\
### Bug Fixes\
\
*   **Deduplicate text content in snapshots** - Fixed an issue where duplicate text content appeared in page snapshots (#909)\
*   **Native mouse drag state** - Fixed incorrect raw native mouse drag state not being properly tracked across `down`, `move`, and `up` events (#872)\
*   **Chrome headless launch failures** - Fixed browser launch failures caused by the `--enable-unsafe-swiftshader` flag in Chrome headless mode (#915)\
*   **Origin-scoped `--headers` persistence** - Restored correct persistence of origin-scoped headers set via `--headers` across navigation commands (#894)\
*   **Relative URLs in WebSocket domain filter** - Fixed handling of relative URLs in the WebSocket domain filter script (#624)\
\
* * *\
\
v0.21.1\
-------\
\
March 18, 2026\
\
### New Features\
\
*   **HAR 1.2 network capture** - Added commands to capture and export network traffic in HAR 1.2 format, including accurate request/response timing, headers, body sizes, and resource types sourced from Chrome DevTools Protocol events (#864)\
*   **Built-in `upgrade` command** - Added `agent-browser upgrade` to self-update the CLI; automatically detects your installation method (npm, Homebrew, or Cargo) and runs the appropriate update command (#898)\
\
    agent-browser upgrade\
\
* * *\
\
v0.21.0\
-------\
\
March 17, 2026\
\
### New Commands\
\
*   **`batch`** -- Execute multiple commands in a single invocation. Pipe a JSON array of string arrays to stdin and receive results sequentially. Supports `--bail` to stop on first error and `--json` for structured output.\
\
    echo '[["open","example.com"],["snapshot"]]' | agent-browser batch --json\
\
*   **`network har start/stop`** -- Capture and export network traffic in HAR 1.2 format.\
\
    agent-browser network har start\
    # ... interact with the page ...\
    agent-browser network har stop ./trace.har\
\
### New Features\
\
*   **iframe support** -- CLI interactions and snapshots now traverse into iframe content, enabling automation of cross-frame pages.\
*   **`--idle-timeout` flag** -- Automatically shut down the daemon after a period of inactivity. Accepts human-friendly formats such as `10s`, `3m`, `1h`, or raw milliseconds. Also available as `AGENT_BROWSER_IDLE_TIMEOUT_MS`.\
*   **Cursor-interactive elements in snapshots** -- Cursor-interactive elements are now embedded directly into the snapshot tree for richer context.\
*   **Brave Browser auto-connect** -- Auto-discovery of Brave Browser for CDP connections on macOS, Linux, and Windows.\
*   **linux-musl (Alpine) builds** -- Pre-built binaries for linux-musl targeting both x64 and arm64, enabling native support for Alpine Linux and other musl-based distributions.\
*   **WebSocket fallback for CDP discovery** -- When HTTP-based CDP endpoint discovery fails, the CLI now falls back to a WebSocket connection automatically.\
\
### Improvements\
\
*   **`--full`/`-f` refactored to command-level flag** -- Moved from a global flag to a per-command flag for clearer scoping.\
*   **Enhanced Chrome launch** -- Added `--user-data-dir` support and configurable launch timeout for more reliable browser startup. Chrome now retries launching up to 3 times on transient startup failures.\
*   **Consecutive `--auto-connect` commands** -- Multiple consecutive auto-connect commands no longer require a full browser relaunch; external connections are correctly identified and reused.\
*   **Batched CDP calls** -- `snapshot -C` and `screenshot --annotate` now batch CDP calls instead of issuing sequential round-trips per element, preventing timeouts on high-latency WSS connections.\
\
### Bug Fixes\
\
*   Fixed remote CDP (WSS) snapshot and screenshot hangs by removing WebSocket message/frame size limits\
*   Fixed Material Design `check`/`uncheck` falling back to JS `.click()` for overlay-based controls\
*   Fixed punctuation characters being dropped in the `type` command\
*   Fixed WebSocket streaming by keeping the StreamServer instance alive\
*   Filtered internal Chrome targets (`chrome://`, `devtools://`) from auto-connect discovery\
*   Fixed `snapshot --selector` scoping to the matched element's subtree\
*   Fixed network idle detection returning prematurely for cached pages\
*   Fixed daemon panic on broken stderr pipe during Chrome launch\
*   Fixed broadcast channel lag being treated as stream closure\
*   Fixed daemon liveness detection for PID namespace isolation (e.g. `unshare`)\
*   Fixed Ubuntu dependency install accidentally removing system packages\
\
* * *\
\
v0.20.0\
-------\
\
March 13, 2026\
\
### Full Native Rust\
\
agent-browser is now 100% native Rust. The Node.js/Playwright daemon has been completely removed -- no Node.js runtime or Playwright dependency is required to run the daemon. The Rust native daemon is now the only implementation.\
\
| Metric | Node.js | Rust |     |\
| --- | --- | --- | --- |\
| Cold start | 1002ms | 617ms | 1.6x faster |\
| Daemon memory | 143 MB | 8 MB | 18x less |\
| Install size | 710 MB | 7 MB | 99x smaller |\
\
    npm install -g agent-browser      # 7 MB install\
    agent-browser install              # download Chrome\
    agent-browser open example.com\
    agent-browser snapshot\
\
### Improvements\
\
*   **Benchmarks** -- Added benchmark suite for comparing native vs Node.js daemon performance across cold start, warm start, memory, and install size.\
*   **Chromium installer hardened** -- Fixed zip path traversal vulnerability in Chrome for Testing installer.\
\
### Bug Fixes\
\
*   Fixed `--headed false` flag not being respected in CLI\
*   Fixed "not found" error pattern in `to_ai_friendly_error` incorrectly catching non-element errors\
*   Fixed storage local key lookup parsing and text output\
*   Fixed Lightpanda engine launch with release binaries\
*   Hardened Lightpanda startup timeouts\
\
* * *\
\
v0.19.0\
-------\
\
March 13, 2026\
\
### New Features\
\
*   **Browserless.io provider** -- Added browserless.io as a browser provider, supported in both Node.js and native daemon paths. Connect to remote Browserless instances using the `--provider browserless` flag or `AGENT_BROWSER_PROVIDER=browserless` environment variable.\
\
    export BROWSERLESS_API_KEY="your-api-key"\
    agent-browser --provider browserless open example.com\
    agent-browser --provider browserless screenshot ./page.png\
\
*   **`clipboard` command** -- Read from and write to the browser clipboard. Supports `read`, `write`, `copy` (simulates Ctrl+C), and `paste` (simulates Ctrl+V) operations.\
\
    agent-browser clipboard read\
    agent-browser clipboard write "Hello, World!"\
    agent-browser clipboard copy\
    agent-browser clipboard paste\
\
*   **Screenshot output configuration** -- New global flags for persistent screenshot settings: `--screenshot-dir`, `--screenshot-quality`, and `--screenshot-format`. Also available as environment variables `AGENT_BROWSER_SCREENSHOT_DIR`, `AGENT_BROWSER_SCREENSHOT_QUALITY`, and `AGENT_BROWSER_SCREENSHOT_FORMAT`.\
\
    agent-browser screenshot --screenshot-dir ./shots\
    agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80\
\
### Bug Fixes\
\
*   Fixed `wait --text` not working in native daemon path\
*   Fixed `BrowserManager.navigate()` and package entry point\
*   Fixed extensions not being loaded from `config.json`\
*   Fixed scroll on page load\
*   Fixed HTML retrieval by using `browser.getLocator()` for selector operations\
\
* * *\
\
v0.18.0\
-------\
\
March 12, 2026\
\
### New Features\
\
*   **`inspect` command** -- Opens Chrome DevTools for the active page by launching a local proxy server that forwards the DevTools frontend to the browser's CDP WebSocket. Agent commands continue to work while DevTools is open.\
\
    agent-browser open example.com\
    agent-browser inspect          # opens DevTools in your browser\
    agent-browser click "Submit"   # commands still work while DevTools is open\
\
*   **`get cdp-url` subcommand** -- Retrieve the Chrome DevTools Protocol WebSocket URL for the active page, useful for connecting external debugging tools.\
\
    agent-browser get cdp-url\
\
*   **Screenshot annotate** -- The `--annotate` flag overlays numbered labels on interactive elements in screenshots.\
\
### Improvements\
\
*   **KERNEL\_API\_KEY now optional** -- External credential injection no longer requires `KERNEL_API_KEY` to be set, making it easier to use Kernel with pre-configured environments.\
*   **Browserbase simplified** -- Removed the `BROWSERBASE_PROJECT_ID` requirement, reducing setup friction for Browserbase users.\
\
### Bug Fixes\
\
*   Fixed Browserbase API using incorrect endpoint to release sessions\
*   Fixed CDP connect paths using hardcoded 10s timeout instead of the configurable default timeout\
*   Fixed lone Unicode surrogates causing errors by sanitizing with `toWellFormed()`\
*   Fixed CDP connection failure on IPv6-first systems\
*   Fixed recordings not inheriting the current viewport settings\
\
* * *\
\
v0.17.1\
-------\
\
March 9, 2026\
\
### Improvements\
\
*   **Viewport scale factor** -- Added support for device scale factor (retina display) in the viewport command via an optional `scale` parameter.\
*   **Webview target support** -- Added webview target type support for better Electron application compatibility. The pages list now includes target type information.\
\
* * *\
\
v0.17.0\
-------\
\
March 8, 2026\
\
### New Features\
\
*   **Lightpanda browser engine support** -- Added `--engine <name>` flag to select the browser engine (`chrome` by default, or `lightpanda`), implying `--native` mode. Configurable via `AGENT_BROWSER_ENGINE` environment variable.\
\
    agent-browser --engine lightpanda open example.com\
\
*   **Dialog dismiss command** -- Added support for `dismiss` subcommand in dialog command parsing.\
\
### Improvements\
\
*   **Daemon startup error reporting** -- Daemon startup errors are now surfaced directly instead of showing an opaque timeout message.\
*   **CDP port discovery** -- Replaced hand-rolled HTTP client with `reqwest` for more reliable CDP port discovery.\
*   **Chrome extensions** -- Extensions now load correctly by forcing headed mode when extensions are present.\
*   **Google Translate bar suppression** -- Suppressed the Google Translate bar in native headless mode to avoid interference.\
*   **Auth cookie persistence** -- Auth cookies are now persisted on browser close in native mode.\
\
### Bug Fixes\
\
*   Fixed native auth login failing due to incompatible encryption format.\
\
### Performance\
\
*   Added benchmarks to the CLI codebase.\
\
* * *\
\
v0.16.0\
-------\
\
March 3, 2026\
\
### New Features\
\
*   **Native Rust daemon (experimental).** A pure Rust daemon that communicates with Chrome directly via the Chrome DevTools Protocol (CDP), eliminating Node.js and Playwright dependencies entirely. Enable with `--native`, `AGENT_BROWSER_NATIVE=1`, or `"native": true` in your config file. Supports 150+ commands with full parity to the default Node.js daemon.\
\
    # Via flag\
    agent-browser --native open example.com\
    \
    # Via environment variable\
    export AGENT_BROWSER_NATIVE=1\
    agent-browser open example.com\
\
Or add to `agent-browser.json`:\
\
    {"native": true}\
\
### Architecture\
\
|     | Default (Node.js) | Native (`--native`) |\
| --- | --- | --- |\
| **Runtime** | Node.js + Playwright | Pure Rust binary |\
| **Protocol** | Playwright protocol | Direct CDP / WebDriver |\
| **Install size** | Larger (Node.js + npm deps) | Smaller (single binary) |\
| **Browser support** | Chromium, Firefox, WebKit | Chromium, Safari (via WebDriver) |\
| **Stability** | Stable | Experimental |\
\
### What's Supported\
\
All core commands work in native mode: navigation, interaction (click, fill, type, press, hover, scroll, drag), observation (snapshot, screenshot, eval), state management (cookies, storage, state save/load), tabs, emulation (viewport, device, timezone, locale, geolocation), streaming, diffing, recording, and profiling.\
\
The native daemon also includes a WebDriver backend for Safari and iOS support.\
\
### Known Limitations\
\
*   Firefox and WebKit are not yet supported (Chromium and Safari only)\
*   Playwright trace format is not available (uses Chrome's built-in tracing)\
*   HAR export is not available\
*   Network route interception uses CDP Fetch domain instead of Playwright's route API\
*   The native and Node.js daemons share the same session socket. Use `agent-browser close` before switching between modes.\
\
See the [Native Mode](https://agent-browser.dev/native-mode)\
 page for full details.\
\
* * *\
\
v0.15.0\
-------\
\
February 25, 2026\
\
### New Features\
\
*   **Authentication vault** -- Store credentials locally (always AES-256-GCM encrypted) and reference them by name. The LLM never sees passwords. Commands: `auth save`, `auth login`, `auth list`, `auth show`, `auth delete`. Passwords can be piped via stdin (`--password-stdin`) to avoid shell history exposure.\
*   **Content boundary markers** -- `--content-boundaries` wraps page-sourced output in structural delimiters with a per-process CSPRNG nonce, so LLMs can distinguish trusted tool output from untrusted page content. In `--json` mode, a `_boundary` object is injected with `nonce` and `origin` fields.\
*   **Domain allowlist** -- `--allowed-domains` restricts navigation, sub-resource requests, WebSocket connections, and EventSource streams to trusted domains. Supports exact match and wildcard prefix patterns (e.g., `*.example.com`).\
*   **Action policy** -- `--action-policy` gates actions using a static JSON policy file with `allow`/`deny` lists across 13 action categories. Auth vault operations bypass policy enforcement.\
*   **Action confirmation** -- `--confirm-actions` requires explicit approval for sensitive action categories. New `confirm` and `deny` commands for orchestrator use. `--confirm-interactive` enables human-in-the-loop terminal prompts (auto-denies if stdin is not a TTY). Pending confirmations auto-deny after 60 seconds.\
*   **Output length limits** -- `--max-output` truncates large page outputs to prevent LLM context flooding.\
*   **`--download-path` option** -- Set a default download directory via flag, `AGENT_BROWSER_DOWNLOAD_PATH` env var, or `downloadPath` config key. Without it, downloads go to a temporary directory deleted when the browser closes.\
*   **`--selector` flag for scroll** -- Scroll within a specific container element instead of the page: `agent-browser scroll down 500 --selector "div.scroll-container"`\
\
    # Auth vault\
    echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin\
    agent-browser auth login github\
    \
    # Security flags\
    agent-browser --content-boundaries --allowed-domains "example.com,*.example.com" --max-output 50000 open https://example.com\
    \
    # Download path\
    agent-browser --download-path ./downloads open https://example.com\
    \
    # Scroll within container\
    agent-browser scroll down 500 --selector "div.content"\
\
### Environment Variables\
\
Six new environment variables for security configuration: `AGENT_BROWSER_CONTENT_BOUNDARIES`, `AGENT_BROWSER_MAX_OUTPUT`, `AGENT_BROWSER_ALLOWED_DOMAINS`, `AGENT_BROWSER_ACTION_POLICY`, `AGENT_BROWSER_CONFIRM_ACTIONS`, `AGENT_BROWSER_CONFIRM_INTERACTIVE`.\
\
* * *\
\
v0.14.0\
-------\
\
February 23, 2026\
\
### New Features\
\
*   **`keyboard` command** -- Type with real keystrokes, insert text, and press shortcuts at the currently focused element without needing a selector (`keyboard type`, `keyboard inserttext`).\
*   **`--color-scheme` flag** -- Persistent dark/light mode preference across browser sessions via flag or `AGENT_BROWSER_COLOR_SCHEME` env var.\
\
    agent-browser keyboard type "Hello world"\
    agent-browser keyboard inserttext "pasted text"\
    agent-browser --color-scheme dark open https://example.com\
\
### Bug Fixes\
\
*   Fixed IPC EAGAIN errors (os error 35/11) with backpressure-aware socket writes, command serialization, and lowered default Playwright timeout to 25s (configurable via `AGENT_BROWSER_DEFAULT_TIMEOUT`).\
*   Fixed remote debugging (CDP) reconnection.\
*   Fixed state load failing when no browser is running.\
*   Fixed `--annotate` flag warning appearing when not explicitly passed via CLI.\
\
* * *\
\
v0.13.0\
-------\
\
February 20, 2026\
\
### New Features\
\
*   **Diff commands** -- Compare snapshots, screenshots, and URLs between page states. Run visual pixel diffs against baseline images, compare accessibility tree snapshots with customizable depth and selectors, and diff two URLs side-by-side with optional screenshot comparison.\
\
    agent-browser diff snapshot\
    agent-browser diff screenshot --baseline before.png\
    agent-browser diff url https://staging.example.com https://prod.example.com\
\
* * *\
\
v0.12.0\
-------\
\
February 18, 2026\
\
### New Features\
\
*   **Annotated screenshots** -- `--annotate` flag overlays numbered labels on interactive elements and prints a legend mapping each label to its element ref. Enables multimodal AI models to reason about visual layout while using the same `@eN` refs for subsequent interactions. Also settable via `AGENT_BROWSER_ANNOTATE` env var.\
\
    agent-browser screenshot --annotate\
\
* * *\
\
v0.11.1\
-------\
\
February 18, 2026\
\
### Documentation\
\
*   Added documentation for command chaining with `&&` across README, CLI help output, docs, and skill files.\
\
* * *\
\
v0.11.0\
-------\
\
February 17, 2026\
\
### New Features\
\
*   **Configuration file support** -- Automatic loading from user (`~/.agent-browser/config.json`) and project (`./agent-browser.json`) directories with priority-based merging.\
*   **Profiler commands** -- Chrome DevTools profiling with `profiler start` and `profiler stop`.\
*   **Browser extension loading** -- `--extension` flag to load browser extensions.\
*   **Storage state management** -- `state save` and `state load` commands for auth state persistence.\
*   **iOS device emulation** -- `--device` flag for device emulation.\
*   **Enhanced click** -- `--new-tab` option for click commands.\
*   **Enhanced find** -- Additional actions and filtering options.\
*   **CDP WebSocket URLs** -- `--cdp` now accepts WebSocket URLs in addition to ports.\
\
* * *\
\
v0.10.0\
-------\
\
February 13, 2026\
\
### New Features\
\
*   **Session persistence** - Automatic save/restore of cookies and localStorage across browser restarts using `--session-name` flag\
*   **Encrypted state** - Optional AES-256-GCM encryption for saved session state data\
*   **State management commands** - New commands for listing, showing, renaming, clearing, and cleaning up session state files\
*   **New tab on click** - Added `--new-tab` option for click commands to open links in new tabs\
\
    # Persist session state\
    agent-browser --session-name myapp open https://example.com\
    \
    # Manage saved states\
    agent-browser state list\
    agent-browser state show myapp\
    agent-browser state clear myapp\
\
* * *\
\
v0.9.4\
------\
\
February 13, 2026\
\
### Bug Fixes\
\
*   Fixed all Clippy lint warnings in the Rust CLI\
\
* * *\
\
v0.9.3\
------\
\
February 12, 2026\
\
### Improvements\
\
*   Added support for custom executable path in CLI browser launch options\
*   Documentation site UI improvements including a new chat component with sheet-based interface\
\
* * *\
\
v0.9.2\
------\
\
February 10, 2026\
\
### Improvements\
\
*   Migrated documentation site to MDX for improved content authoring\
*   Added AI-powered docs chat feature\
*   Updated README with Homebrew installation instructions for macOS users\
\
* * *\
\
v0.9.1\
------\
\
February 5, 2026\
\
### New Features\
\
*   **`--allow-file-access` flag** - Enable opening and interacting with local `file://` URLs (PDFs, HTML files) by passing Chromium flags that allow JavaScript access to local files\
*   **`-C`/`--cursor` flag for snapshots** - Include cursor-interactive elements like divs with onclick handlers or `cursor:pointer` styles\
\
    agent-browser --allow-file-access open file:///path/to/document.pdf\
    agent-browser snapshot -C\
\
* * *\
\
v0.9.0\
------\
\
February 3, 2026\
\
### New Features\
\
*   **iOS Simulator support** - Mobile Safari testing via Appium with real device and simulator support\
\
    # List available iOS simulators\
    agent-browser device list\
    \
    # Launch on iOS device\
    agent-browser -p ios --device "iPhone 16 Pro" open https://example.com\
    \
    # Touch interactions\
    agent-browser tap @e1\
    agent-browser swipe up\
\
* * *\
\
v0.8.10\
-------\
\
February 2, 2026\
\
### Improvements\
\
*   Added `--stdin` flag for eval command to read JavaScript from stdin, enabling heredoc usage for multiline scripts\
*   Fixed binary permission issues on macOS/Linux when postinstall scripts don't run\
\
* * *\
\
v0.8.9\
------\
\
February 2, 2026\
\
### Improvements\
\
*   Added `--stdin` flag for eval command to read JavaScript from stdin\
\
* * *\
\
v0.8.8\
------\
\
February 2, 2026\
\
### Improvements\
\
*   Added base64 encoding support for the eval command with `-b`/`--base64` flag to avoid shell escaping issues\
*   Updated documentation with AI agent setup instructions\
\
* * *\
\
v0.8.7\
------\
\
February 2, 2026\
\
### Bug Fixes\
\
*   Fixed browser launch options not being passed correctly when using persistent profiles\
*   Added pre-flight checks for socket path length limits and directory write permissions\
*   Improved error handling to properly exit with failure status when browser launch fails\
\
* * *\
\
v0.8.6\
------\
\
January 31, 2026\
\
### Bug Fixes\
\
*   Improved daemon connection reliability with automatic retry logic for transient errors\
*   CLI now cleans up stale socket and PID files before starting a new daemon\
\
* * *\
\
v0.8.5\
------\
\
January 29, 2026\
\
### Bug Fixes\
\
*   Fixed version synchronization to automatically update Cargo.lock alongside Cargo.toml during releases\
*   Made the CLI binary executable in the npm package\
\
* * *\
\
v0.8.4\
------\
\
January 27, 2026\
\
### Bug Fixes\
\
*   Fixed "Daemon not found" error when running through AI agents by resolving symlinks in the executable path\
\
* * *\
\
v0.8.3\
------\
\
January 27, 2026\
\
### Improvements\
\
*   Replaced shell-based CLI wrappers with a cross-platform Node.js wrapper to enable npx support on Windows\
*   Added postinstall logic to patch npm bin entry on global installs for zero-overhead native binary invocation\
*   Added CI tests to verify global installation across all platforms\
\
* * *\
\
v0.8.2\
------\
\
January 26, 2026\
\
### Bug Fixes\
\
*   Fixed the Windows CMD wrapper to use the native binary directly instead of routing through Node.js\
*   Added retry logic to CI install command for transient browser installation failures\
\
* * *\
\
v0.8.1\
------\
\
January 26, 2026\
\
### Improvements\
\
*   Improved release workflow to validate binary file sizes and ensure binaries are executable after npm install\
*   Updated documentation site with a new mobile navigation system\
\
* * *\
\
v0.8.0\
------\
\
January 26, 2026\
\
### New Features\
\
*   **Kernel cloud browser provider** - Connect to Kernel (kernel.sh) for remote browser infrastructure with stealth mode and persistent profiles\
\
    # Via -p flag\
    agent-browser -p kernel open https://example.com\
    \
    # Via environment variable\
    export AGENT_BROWSER_PROVIDER=kernel\
    export KERNEL_API_KEY=your-api-key\
    agent-browser open https://example.com\
    \
    # With persistent profile\
    export KERNEL_PROFILE_NAME=my-profile\
    agent-browser open https://example.com\
\
*   **Ignore HTTPS certificate errors** - New flag for working with self-signed certificates and development environments\
\
    agent-browser --ignore-https-errors open https://localhost:3000\
\
*   **Enhanced cookie management** - Extended `cookies set` command with additional flags for setting cookies before page load\
\
    agent-browser cookies set session_id "abc123" --url https://app.example.com --httpOnly --secure\
    agent-browser cookies set token "xyz" --domain .example.com --path /api --expires 1735689600\
\
### Bug Fixes\
\
*   Fixed tab list command not recognizing new pages opened via clicks or `target="_blank"` links\
*   Fixed `check` command hanging indefinitely\
*   Fixed `set device` not applying deviceScaleFactor - HiDPI screenshots now work correctly\
*   Fixed state load and profile persistence not working in v0.7.6\
*   Screenshots now save to temp directory when no path is provided\
\
### Security\
\
*   Daemon and stream server now reject cross-origin connections\
\
* * *\
\
v0.7.1\
------\
\
January 23, 2026\
\
### Bug Fixes\
\
*   **Fix native binary distribution** - Native binaries for all platforms (Linux x64/arm64, macOS x64/arm64, Windows x64) are now included in the npm package. Previously, the release workflow published to npm before building binaries, causing "No binary found" errors on installation.\
\
* * *\
\
v0.7.0\
------\
\
January 23, 2026\
\
### New Features\
\
*   **Cloud browser providers** - Connect to Browserbase or Browser Use for remote browser infrastructure\
\
    # Via -p flag (recommended)\
    agent-browser -p browserbase open https://example.com\
    agent-browser -p browseruse open https://example.com\
    \
    # Via environment variable\
    export AGENT_BROWSER_PROVIDER=browserbase\
    agent-browser open https://example.com\
\
*   **Persistent browser profiles** - Store cookies, localStorage, and login sessions across browser restarts\
\
    agent-browser --profile ~/.myapp-profile open myapp.com\
    # Login persists across restarts\
\
*   **Remote CDP WebSocket URLs** - Connect to remote browser services via WebSocket\
\
    agent-browser --cdp "wss://browser-service.com/cdp?token=..." snapshot\
\
*   **`download` command** - Trigger downloads and wait for completion\
\
    agent-browser download @e1 ./file.pdf\
    agent-browser wait --download ./output.zip --timeout 30000\
\
*   **Browser launch configuration** - Fine-grained control over browser startup\
\
    agent-browser --args "--disable-gpu,--no-sandbox" open example.com\
    agent-browser --user-agent "Custom UA" open example.com\
    agent-browser --proxy-bypass "localhost,*.internal" open example.com\
\
*   **Enhanced skills** - Hierarchical structure with references and templates for Claude Code\
\
### Bug Fixes\
\
*   Screenshot command now supports refs and has improved error messages\
*   WebSocket URLs work in `connect` command\
*   Fixed socket file location (uses `~/.agent-browser` instead of TMPDIR)\
*   Windows binary path fix (.exe extension)\
*   State load and path-based actions now show correct output messages\
\
### Documentation\
\
*   Added Claude Code marketplace plugin installation instructions\
*   Updated skill documentation with references and templates\
*   Improved error documentation\
\
* * *\
\
v0.6.0\
------\
\
January 18, 2026\
\
### New Features\
\
*   **Video recording** - Record browser sessions to WebM using Playwright's native recording\
\
    agent-browser record start ./demo.webm\
    agent-browser click @e1\
    agent-browser record stop\
\
*   **`connect` command** - Connect to a browser via CDP and persist the connection for subsequent commands\
\
    agent-browser connect 9222\
    agent-browser snapshot  # No --cdp needed after connect\
\
*   **`--proxy` flag** - Configure browser proxy with optional authentication\
\
    agent-browser --proxy http://user:pass@proxy.com:8080 open example.com\
\
*   **`get styles` command** - Extract computed styles from elements\
\
    agent-browser get styles "button"\
\
*   **Claude marketplace plugin** - Added `.claude-plugin/marketplace.json` for Claude Code integration\
*   **Enhanced network output** - `network requests` now shows method, URL, and resource type\
*   **`--version` flag** - Display CLI version\
\
### Bug Fixes\
\
*   Fix Windows daemon startup and port calculation\
*   Support `libasound2t64` on newer Ubuntu versions (24.04+)\
*   Prevent CDP timeout on empty URL tabs\
*   Output screenshot as base64 when no path provided\
*   Resolve refs in `get value` command\
*   Support URL parameter in `tab new` command\
*   Allow `about:`, `data:`, and `file:` URL schemes\
*   Detect stale unix socket by attempting connection\
*   Respect `AGENT_BROWSER_HEADED` environment variable\
*   Handle SIGPIPE to prevent panic when piping to `head`/`tail`\
*   Fix null path validation in screenshot command\
\
### Protocol Alignment\
\
These changes align the CLI with the daemon protocol for consistency:\
\
*   `select` command now uses `values` field (supports multiple selections)\
*   `frame main` uses `mainframe` action\
*   `mouse wheel` uses `wheel` action\
*   `set media` uses `emulatemedia` action\
*   Console output uses `messages` field\
\
### Documentation\
\
*   Expanded SKILL.md with comprehensive command reference\
*   Updated README with new commands and options\
*   Updated CDP mode documentation with `connect` workflow\
\
Ask AI⌘I

---

# Next.js + Vercel | agent-browser

Next.js + Vercel

Copy Page

Next.js + Vercel
================

Run agent-browser from a Next.js app on Vercel using Vercel Sandbox. A Linux microVM spins up on demand, runs agent-browser + Chrome, and shuts down. No binary size limits, no Chromium bundling complexity.

Setup
-----

    pnpm add @vercel/sandbox

Server action
-------------

The Vercel Sandbox runs Amazon Linux. Chromium requires system libraries that are not installed by default, so fresh sandboxes need a `dnf install` step before agent-browser can launch Chrome. Use a sandbox snapshot (below) to skip this entirely in production.

    "use server";
    import { Sandbox } from "@vercel/sandbox";
    
    const snapshotId = process.env.AGENT_BROWSER_SNAPSHOT_ID;
    
    const CHROMIUM_SYSTEM_DEPS = [\
      "nss", "nspr", "libxkbcommon", "atk", "at-spi2-atk", "at-spi2-core",\
      "libXcomposite", "libXdamage", "libXrandr", "libXfixes", "libXcursor",\
      "libXi", "libXtst", "libXScrnSaver", "libXext", "mesa-libgbm", "libdrm",\
      "mesa-libGL", "mesa-libEGL", "cups-libs", "alsa-lib", "pango", "cairo",\
      "gtk3", "dbus-libs",\
    ];
    
    function getSandboxCredentials() {
      if (
        process.env.VERCEL_TOKEN &&
        process.env.VERCEL_TEAM_ID &&
        process.env.VERCEL_PROJECT_ID
      ) {
        return {
          token: process.env.VERCEL_TOKEN,
          teamId: process.env.VERCEL_TEAM_ID,
          projectId: process.env.VERCEL_PROJECT_ID,
        };
      }
      return {};
    }
    
    async function withBrowser​​T​​(
      fn: (sandbox: InstanceType<typeof Sandbox>) => Promise​​T​​,
    ): Promise​​T​​ {
      const credentials = getSandboxCredentials();
    
      const sandbox = snapshotId
        ? await Sandbox.create({
            ...credentials,
            source: { type: "snapshot", snapshotId },
            timeout: 120_000,
          })
        : await Sandbox.create({ ...credentials, runtime: "node24", timeout: 120_000 });
    
      if (!snapshotId) {
        await sandbox.runCommand("sh", [\
          "-c",\
          `sudo dnf clean all 2>&1 && sudo dnf install -y --skip-broken ${CHROMIUM_SYSTEM_DEPS.join(" ")} 2>&1 && sudo ldconfig 2>&1`,\
        ]);
        await sandbox.runCommand("npm", ["install", "-g", "agent-browser"]);
        await sandbox.runCommand("npx", ["agent-browser", "install"]);
      }
    
      try {
        return await fn(sandbox);
      } finally {
        await sandbox.stop();
      }
    }
    
    export async function screenshotUrl(url: string) {
      return withBrowser(async (sandbox) => {
        await sandbox.runCommand("agent-browser", ["open", url]);
    
        const ssResult = await sandbox.runCommand("agent-browser", [\
          "screenshot", "--json",\
        ]);
        const ssPath = JSON.parse(await ssResult.stdout())?.data?.path;
        const b64Result = await sandbox.runCommand("base64", ["-w", "0", ssPath]);
        const screenshot = (await b64Result.stdout()).trim();
    
        await sandbox.runCommand("agent-browser", ["close"]);
        return { ok: true, screenshot };
      });
    }
    
    export async function snapshotUrl(url: string) {
      return withBrowser(async (sandbox) => {
        await sandbox.runCommand("agent-browser", ["open", url]);
    
        const result = await sandbox.runCommand("agent-browser", [\
          "snapshot", "-i", "-c",\
        ]);
        const snapshot = await result.stdout();
    
        await sandbox.runCommand("agent-browser", ["close"]);
        return { ok: true, snapshot };
      });
    }

Sandbox snapshots
-----------------

Without optimization, each Sandbox run installs system dependencies + agent-browser + Chromium from scratch (~30 seconds). A **sandbox snapshot** is a saved VM image with everything pre-installed -- like a Docker image for Vercel Sandbox. When `AGENT_BROWSER_SNAPSHOT_ID` is set, the sandbox boots from that image instead of installing, bringing startup down to sub-second.

This is different from an agent-browser _accessibility snapshot_ (which dumps a page's accessibility tree). A sandbox snapshot is a Vercel infrastructure concept.

Create a sandbox snapshot by running the helper script once:

    npx tsx scripts/create-snapshot.ts

The script spins up a fresh sandbox, installs system dependencies + agent-browser + Chromium, saves the VM state, and prints the snapshot ID:

    AGENT_BROWSER_SNAPSHOT_ID=snap_xxxxxxxxxxxx

Add this to your Vercel project environment variables (or `.env.local` for local development). Recommended for any production deployment.

Authentication
--------------

On Vercel deployments, the Sandbox SDK authenticates automatically via OIDC. For local development, provide explicit credentials:

| Variable | Description |
| --- | --- |
| `VERCEL_TOKEN` | Vercel personal access token |
| `VERCEL_TEAM_ID` | Vercel team ID |
| `VERCEL_PROJECT_ID` | Vercel project ID |

When all three are set, they are passed to `Sandbox.create()`. When absent, the SDK falls back to `VERCEL_OIDC_TOKEN` (automatic on Vercel).

Scheduled workflows (cron)
--------------------------

For recurring tasks like daily monitoring, use Vercel Cron Jobs:

    // app/api/cron/monitor/route.ts
    export async function GET() {
      const result = await withBrowser(async (sandbox) => {
        await sandbox.runCommand("agent-browser", [\
          "open", "https://example.com/pricing",\
        ]);
        const snap = await sandbox.runCommand("agent-browser", [\
          "snapshot", "-i", "-c",\
        ]);
        await sandbox.runCommand("agent-browser", ["close"]);
        return await snap.stdout();
      });
    
      // Process results, send alerts, store data...
      return Response.json({ ok: true, snapshot: result });
    }

    // vercel.json
    {
      "crons": [\
        { "path": "/api/cron/monitor", "schedule": "0 9 * * *" }\
      ]
    }

Environment variables
---------------------

| Variable | Description |
| --- | --- |
| `AGENT_BROWSER_SNAPSHOT_ID` | Sandbox snapshot ID for sub-second startup (see above) |
| `VERCEL_TOKEN` | Vercel personal access token (for local dev; OIDC is automatic on Vercel) |
| `VERCEL_TEAM_ID` | Vercel team ID (for local dev) |
| `VERCEL_PROJECT_ID` | Vercel project ID (for local dev) |

Demo app
--------

A working demo with streaming progress UI, rate limiting, and a deploy-to-Vercel button is at [`examples/environments/`](https://github.com/vercel-labs/agent-browser/tree/main/examples/environments)
.

Ask AI⌘I

---