{"id":41215771,"url":"https://github.com/vercel-labs/agent-browser","last_synced_at":"2026-04-17T01:06:59.614Z","repository":{"id":332038165,"uuid":"1132001614","full_name":"vercel-labs/agent-browser","owner":"vercel-labs","description":"Browser automation CLI for AI agents","archived":false,"fork":false,"pushed_at":"2026-03-31T01:54:59.000Z","size":16225,"stargazers_count":25830,"open_issues_count":345,"forks_count":1564,"subscribers_count":68,"default_branch":"main","last_synced_at":"2026-03-31T03:39:31.192Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://agent-browser.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vercel-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-11T05:38:15.000Z","updated_at":"2026-03-31T03:34:05.000Z","dependencies_parsed_at":"2026-03-15T18:03:29.069Z","dependency_job_id":null,"html_url":"https://github.com/vercel-labs/agent-browser","commit_stats":null,"previous_names":["vercel-labs/agent-browser"],"tags_count":64,"template":false,"template_full_name":null,"purl":"pkg:github/vercel-labs/agent-browser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel-labs%2Fagent-browser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel-labs%2Fagent-browser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel-labs%2Fagent-browser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel-labs%2Fagent-browser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vercel-labs","download_url":"https://codeload.github.com/vercel-labs/agent-browser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel-labs%2Fagent-browser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31407654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-23T00:01:14.264Z","updated_at":"2026-04-17T01:06:59.599Z","avatar_url":"https://github.com/vercel-labs.png","language":"Rust","readme":"# agent-browser\n\nBrowser automation CLI for AI agents. Fast native Rust CLI.\n\n## Installation\n\n### Global Installation (recommended)\n\nInstalls the native Rust binary:\n\n```bash\nnpm install -g agent-browser\nagent-browser install  # Download Chrome from Chrome for Testing (first time only)\n```\n\n### Project Installation (local dependency)\n\nFor projects that want to pin the version in `package.json`:\n\n```bash\nnpm install agent-browser\nagent-browser install\n```\n\nThen use via `package.json` scripts or by invoking `agent-browser` directly.\n\n### Homebrew (macOS)\n\n```bash\nbrew install agent-browser\nagent-browser install  # Download Chrome from Chrome for Testing (first time only)\n```\n\n### Cargo (Rust)\n\n```bash\ncargo install agent-browser\nagent-browser install  # Download Chrome from Chrome for Testing (first time only)\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/vercel-labs/agent-browser\ncd agent-browser\npnpm install\npnpm build\npnpm build:native   # Requires Rust (https://rustup.rs)\npnpm link --global  # Makes agent-browser available globally\nagent-browser install\n```\n\n### Linux Dependencies\n\nOn Linux, install system dependencies:\n\n```bash\nagent-browser install --with-deps\n```\n\n### Updating\n\nUpgrade to the latest version:\n\n```bash\nagent-browser upgrade\n```\n\nDetects your installation method (npm, Homebrew, or Cargo) and runs the appropriate update command automatically.\n\n### Requirements\n\n- **Chrome** - Run `agent-browser install` to download Chrome from [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing/) (Google's official automation channel). Existing Chrome, Brave, Playwright, and Puppeteer installations are detected automatically. No Playwright or Node.js required for the daemon.\n- **Rust** - Only needed when building from source (see From Source above).\n\n## Quick Start\n\n```bash\nagent-browser open example.com\nagent-browser snapshot                    # Get accessibility tree with refs\nagent-browser click @e2                   # Click by ref from snapshot\nagent-browser fill @e3 \"test@example.com\" # Fill by ref\nagent-browser get text @e1                # Get text by ref\nagent-browser screenshot page.png\nagent-browser close\n```\n\n### Traditional Selectors (also supported)\n\n```bash\nagent-browser click \"#submit\"\nagent-browser fill \"#email\" \"test@example.com\"\nagent-browser find role button click --name \"Submit\"\n```\n\n## Commands\n\n### Core Commands\n\n```bash\nagent-browser open \u003curl\u003e              # Navigate to URL (aliases: goto, navigate)\nagent-browser click \u003csel\u003e             # Click element (--new-tab to open in new tab)\nagent-browser dblclick \u003csel\u003e          # Double-click element\nagent-browser focus \u003csel\u003e             # Focus element\nagent-browser type \u003csel\u003e \u003ctext\u003e       # Type into element\nagent-browser fill \u003csel\u003e \u003ctext\u003e       # Clear and fill\nagent-browser press \u003ckey\u003e             # Press key (Enter, Tab, Control+a) (alias: key)\nagent-browser keyboard type \u003ctext\u003e    # Type with real keystrokes (no selector, current focus)\nagent-browser keyboard inserttext \u003ctext\u003e  # Insert text without key events (no selector)\nagent-browser keydown \u003ckey\u003e           # Hold key down\nagent-browser keyup \u003ckey\u003e             # Release key\nagent-browser hover \u003csel\u003e             # Hover element\nagent-browser select \u003csel\u003e \u003cval\u003e      # Select dropdown option\nagent-browser check \u003csel\u003e             # Check checkbox\nagent-browser uncheck \u003csel\u003e           # Uncheck checkbox\nagent-browser scroll \u003cdir\u003e [px]       # Scroll (up/down/left/right, --selector \u003csel\u003e)\nagent-browser scrollintoview \u003csel\u003e    # Scroll element into view (alias: scrollinto)\nagent-browser drag \u003csrc\u003e \u003ctgt\u003e        # Drag and drop\nagent-browser upload \u003csel\u003e \u003cfiles\u003e    # Upload files\nagent-browser screenshot [path]       # Take screenshot (--full for full page, saves to a temporary directory if no path)\nagent-browser screenshot --annotate   # Annotated screenshot with numbered element labels\nagent-browser screenshot --screenshot-dir ./shots    # Save to custom directory\nagent-browser screenshot --screenshot-format jpeg --screenshot-quality 80\nagent-browser pdf \u003cpath\u003e              # Save as PDF\nagent-browser snapshot                # Accessibility tree with refs (best for AI)\nagent-browser eval \u003cjs\u003e               # Run JavaScript (-b for base64, --stdin for piped input)\nagent-browser connect \u003cport\u003e          # Connect to browser via CDP\nagent-browser stream enable [--port \u003cport\u003e]  # Start runtime WebSocket streaming\nagent-browser stream status           # Show runtime streaming state and bound port\nagent-browser stream disable          # Stop runtime WebSocket streaming\nagent-browser close                   # Close browser (aliases: quit, exit)\nagent-browser close --all             # Close all active sessions\nagent-browser chat \"\u003cinstruction\u003e\"    # AI chat: natural language browser control (single-shot)\nagent-browser chat                    # AI chat: interactive REPL mode\n```\n\n### Get Info\n\n```bash\nagent-browser get text \u003csel\u003e          # Get text content\nagent-browser get html \u003csel\u003e          # Get innerHTML\nagent-browser get value \u003csel\u003e         # Get input value\nagent-browser get attr \u003csel\u003e \u003cattr\u003e   # Get attribute\nagent-browser get title               # Get page title\nagent-browser get url                 # Get current URL\nagent-browser get cdp-url             # Get CDP WebSocket URL (for DevTools, debugging)\nagent-browser get count \u003csel\u003e         # Count matching elements\nagent-browser get box \u003csel\u003e           # Get bounding box\nagent-browser get styles \u003csel\u003e        # Get computed styles\n```\n\n### Check State\n\n```bash\nagent-browser is visible \u003csel\u003e        # Check if visible\nagent-browser is enabled \u003csel\u003e        # Check if enabled\nagent-browser is checked \u003csel\u003e        # Check if checked\n```\n\n### Find Elements (Semantic Locators)\n\n```bash\nagent-browser find role \u003crole\u003e \u003caction\u003e [value]       # By ARIA role\nagent-browser find text \u003ctext\u003e \u003caction\u003e               # By text content\nagent-browser find label \u003clabel\u003e \u003caction\u003e [value]     # By label\nagent-browser find placeholder \u003cph\u003e \u003caction\u003e [value]  # By placeholder\nagent-browser find alt \u003ctext\u003e \u003caction\u003e                # By alt text\nagent-browser find title \u003ctext\u003e \u003caction\u003e              # By title attr\nagent-browser find testid \u003cid\u003e \u003caction\u003e [value]       # By data-testid\nagent-browser find first \u003csel\u003e \u003caction\u003e [value]       # First match\nagent-browser find last \u003csel\u003e \u003caction\u003e [value]        # Last match\nagent-browser find nth \u003cn\u003e \u003csel\u003e \u003caction\u003e [value]     # Nth match\n```\n\n**Actions:** `click`, `fill`, `type`, `hover`, `focus`, `check`, `uncheck`, `text`\n\n**Options:** `--name \u003cname\u003e` (filter role by accessible name), `--exact` (require exact text match)\n\n**Examples:**\n\n```bash\nagent-browser find role button click --name \"Submit\"\nagent-browser find text \"Sign In\" click\nagent-browser find label \"Email\" fill \"test@test.com\"\nagent-browser find first \".item\" click\nagent-browser find nth 2 \"a\" text\n```\n\n### Wait\n\n```bash\nagent-browser wait \u003cselector\u003e         # Wait for element to be visible\nagent-browser wait \u003cms\u003e               # Wait for time (milliseconds)\nagent-browser wait --text \"Welcome\"   # Wait for text to appear (substring match)\nagent-browser wait --url \"**/dash\"    # Wait for URL pattern\nagent-browser wait --load networkidle # Wait for load state\nagent-browser wait --fn \"window.ready === true\"  # Wait for JS condition\n\n# Wait for text/element to disappear\nagent-browser wait --fn \"!document.body.innerText.includes('Loading...')\"\nagent-browser wait \"#spinner\" --state hidden\n```\n\n**Load states:** `load`, `domcontentloaded`, `networkidle`\n\n### Batch Execution\n\nExecute multiple commands in a single invocation. Commands can be passed as\nquoted arguments or piped as JSON via stdin. This avoids per-command process\nstartup overhead when running multi-step workflows.\n\n```bash\n# Argument mode: each quoted argument is a full command\nagent-browser batch \"open https://example.com\" \"snapshot -i\" \"screenshot\"\n\n# With --bail to stop on first error\nagent-browser batch --bail \"open https://example.com\" \"click @e1\" \"screenshot\"\n\n# Stdin mode: pipe commands as JSON\necho '[\n  [\"open\", \"https://example.com\"],\n  [\"snapshot\", \"-i\"],\n  [\"click\", \"@e1\"],\n  [\"screenshot\", \"result.png\"]\n]' | agent-browser batch --json\n```\n\n### Clipboard\n\n```bash\nagent-browser clipboard read                      # Read text from clipboard\nagent-browser clipboard write \"Hello, World!\"     # Write text to clipboard\nagent-browser clipboard copy                      # Copy current selection (Ctrl+C)\nagent-browser clipboard paste                     # Paste from clipboard (Ctrl+V)\n```\n\n### Mouse Control\n\n```bash\nagent-browser mouse move \u003cx\u003e \u003cy\u003e      # Move mouse\nagent-browser mouse down [button]     # Press button (left/right/middle)\nagent-browser mouse up [button]       # Release button\nagent-browser mouse wheel \u003cdy\u003e [dx]   # Scroll wheel\n```\n\n### Browser Settings\n\n```bash\nagent-browser set viewport \u003cw\u003e \u003ch\u003e [scale]  # Set viewport size (scale for retina, e.g. 2)\nagent-browser set device \u003cname\u003e       # Emulate device (\"iPhone 14\")\nagent-browser set geo \u003clat\u003e \u003clng\u003e     # Set geolocation\nagent-browser set offline [on|off]    # Toggle offline mode\nagent-browser set headers \u003cjson\u003e      # Extra HTTP headers\nagent-browser set credentials \u003cu\u003e \u003cp\u003e # HTTP basic auth\nagent-browser set media [dark|light]  # Emulate color scheme\n```\n\n### Cookies \u0026 Storage\n\n```bash\nagent-browser cookies                 # Get all cookies\nagent-browser cookies set \u003cname\u003e \u003cval\u003e # Set cookie\nagent-browser cookies clear           # Clear cookies\n\nagent-browser storage local           # Get all localStorage\nagent-browser storage local \u003ckey\u003e     # Get specific key\nagent-browser storage local set \u003ck\u003e \u003cv\u003e  # Set value\nagent-browser storage local clear     # Clear all\n\nagent-browser storage session         # Same for sessionStorage\n```\n\n### Network\n\n```bash\nagent-browser network route \u003curl\u003e              # Intercept requests\nagent-browser network route \u003curl\u003e --abort      # Block requests\nagent-browser network route \u003curl\u003e --body \u003cjson\u003e  # Mock response\nagent-browser network unroute [url]            # Remove routes\nagent-browser network requests                 # View tracked requests\nagent-browser network requests --filter api    # Filter requests\nagent-browser network requests --type xhr,fetch  # Filter by resource type\nagent-browser network requests --method POST   # Filter by HTTP method\nagent-browser network requests --status 2xx    # Filter by status (200, 2xx, 400-499)\nagent-browser network request \u003crequestId\u003e      # View full request/response detail\nagent-browser network har start                # Start HAR recording\nagent-browser network har stop [output.har]    # Stop and save HAR (temp path if omitted)\n```\n\n### Tabs \u0026 Windows\n\n```bash\nagent-browser tab                              # List tabs (shows `tabId` and optional label)\nagent-browser tab new [url]                    # New tab (optionally with URL)\nagent-browser tab new --label docs [url]       # New tab with a user-assigned label\nagent-browser tab \u003ct\u003cN\u003e|label\u003e                 # Switch to a tab by id or label\nagent-browser tab close [t\u003cN\u003e|label]           # Close a tab (defaults to active)\nagent-browser window new                       # New window\n```\n\nTab ids are stable strings of the form `t1`, `t2`, `t3`. They're never reused\nwithin a session, so scripts and agents can keep referring to the same tab\neven after other tabs are opened or closed. Positional integers like `tab 2`\nare **not** accepted; the `t` prefix disambiguates handles from indices and\nmirrors the `@e1` convention used for element refs.\n\nYou can also assign a memorable label (`docs`, `app`, `admin`) and use it\ninterchangeably with the id. Labels are never auto-generated and never\nrewritten on navigation — they're yours to name and keep:\n\n```bash\nagent-browser tab new --label docs https://docs.example.com\nagent-browser tab docs               # switch to the docs tab\nagent-browser snapshot               # populate refs for docs\nagent-browser click @e3              # click uses docs's refs\nagent-browser tab close docs         # close by label\n```\n\n### Frames\n\n```bash\nagent-browser frame \u003csel\u003e             # Switch to iframe\nagent-browser frame main              # Back to main frame\n```\n\n### Dialogs\n\n```bash\nagent-browser dialog accept [text]    # Accept (with optional prompt text)\nagent-browser dialog dismiss          # Dismiss\nagent-browser dialog status           # Check if a dialog is currently open\n```\n\nBy 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.\n\nWhen a JavaScript dialog is pending, all command responses include a `warning` field with the dialog type and message.\n\n### Diff\n\n```bash\nagent-browser diff snapshot                              # Compare current vs last snapshot\nagent-browser diff snapshot --baseline before.txt        # Compare current vs saved snapshot file\nagent-browser diff snapshot --selector \"#main\" --compact # Scoped snapshot diff\nagent-browser diff screenshot --baseline before.png      # Visual pixel diff against baseline\nagent-browser diff screenshot --baseline b.png -o d.png  # Save diff image to custom path\nagent-browser diff screenshot --baseline b.png -t 0.2    # Adjust color threshold (0-1)\nagent-browser diff url https://v1.com https://v2.com     # Compare two URLs (snapshot diff)\nagent-browser diff url https://v1.com https://v2.com --screenshot  # Also visual diff\nagent-browser diff url https://v1.com https://v2.com --wait-until networkidle  # Custom wait strategy\nagent-browser diff url https://v1.com https://v2.com --selector \"#main\"  # Scope to element\n```\n\n### Debug\n\n```bash\nagent-browser trace start [path]      # Start recording trace\nagent-browser trace stop [path]       # Stop and save trace\nagent-browser profiler start          # Start Chrome DevTools profiling\nagent-browser profiler stop [path]    # Stop and save profile (.json)\nagent-browser console                 # View console messages (log, error, warn, info)\nagent-browser console --json          # JSON output with raw CDP args for programmatic access\nagent-browser console --clear         # Clear console\nagent-browser errors                  # View page errors (uncaught JavaScript exceptions)\nagent-browser errors --clear          # Clear errors\nagent-browser highlight \u003csel\u003e         # Highlight element\nagent-browser inspect                 # Open Chrome DevTools for the active page\nagent-browser state save \u003cpath\u003e       # Save auth state\nagent-browser state load \u003cpath\u003e       # Load auth state\nagent-browser state list              # List saved state files\nagent-browser state show \u003cfile\u003e       # Show state summary\nagent-browser state rename \u003cold\u003e \u003cnew\u003e # Rename state file\nagent-browser state clear [name]      # Clear states for session\nagent-browser state clear --all       # Clear all saved states\nagent-browser state clean --older-than \u003cdays\u003e  # Delete old states\n```\n\n### Navigation\n\n```bash\nagent-browser back                    # Go back\nagent-browser forward                 # Go forward\nagent-browser reload                  # Reload page\n```\n\n### Setup\n\n```bash\nagent-browser install                 # Download Chrome from Chrome for Testing (Google's official automation channel)\nagent-browser install --with-deps     # Also install system deps (Linux)\nagent-browser upgrade                 # Upgrade agent-browser to the latest version\nagent-browser doctor                  # Diagnose the install and auto-clean stale daemon files\nagent-browser doctor --fix            # Also run destructive repairs (reinstall Chrome, purge old state, ...)\nagent-browser doctor --offline --quick  # Skip network probes and the live launch test\n```\n\n`doctor` checks your environment, Chrome install, daemon state, config files,\nencryption key, providers, network reachability, and runs a live headless\nbrowser launch test. Stale socket/pid sidecar files are auto-cleaned. Output\nis also available as `--json` for agents.\n\n### Skills\n\n```bash\nagent-browser skills                  # List available skills\nagent-browser skills list             # Same as above\nagent-browser skills get \u003cname\u003e       # Output a skill's full content\nagent-browser skills get \u003cname\u003e --full  # Include references and templates\nagent-browser skills get --all        # Output every skill\nagent-browser skills path [name]      # Print skill directory path\n```\n\nServes bundled skill content that always matches the installed CLI version. AI agents use this to get current instructions rather than relying on cached copies. Set `AGENT_BROWSER_SKILLS_DIR` to override the skills directory path.\n\n## Authentication\n\nagent-browser provides multiple ways to persist login sessions so you don't re-authenticate every run.\n\n### Quick summary\n\n| Approach | Best for | Flag / Env |\n|----------|----------|------------|\n| **Chrome profile reuse** | Reuse your existing Chrome login state (cookies, sessions) with zero setup | `--profile \u003cname\u003e` / `AGENT_BROWSER_PROFILE` |\n| **Persistent profile** | Full browser state (cookies, IndexedDB, service workers, cache) across restarts | `--profile \u003cpath\u003e` / `AGENT_BROWSER_PROFILE` |\n| **Session persistence** | Auto-save/restore cookies + localStorage by name | `--session-name \u003cname\u003e` / `AGENT_BROWSER_SESSION_NAME` |\n| **Import from your browser** | Grab auth from a Chrome session you already logged into | `--auto-connect` + `state save` |\n| **State file** | Load a previously saved state JSON on launch | `--state \u003cpath\u003e` / `AGENT_BROWSER_STATE` |\n| **Auth vault** | Store credentials locally (encrypted), login by name | `auth save` / `auth login` |\n\n### Import auth from your browser\n\nIf you are already logged in to a site in Chrome, you can grab that auth state and reuse it:\n\n```bash\n# 1. Launch Chrome with remote debugging enabled\n#    macOS:\n\"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\" --remote-debugging-port=9222\n#    Or use --auto-connect to discover an already-running Chrome\n\n# 2. Connect and save the authenticated state\nagent-browser --auto-connect state save ./my-auth.json\n\n# 3. Use the saved auth in future sessions\nagent-browser --state ./my-auth.json open https://app.example.com/dashboard\n\n# 4. Or use --session-name for automatic persistence\nagent-browser --session-name myapp state load ./my-auth.json\n# From now on, --session-name myapp auto-saves/restores this state\n```\n\n\u003e **Security notes:**\n\u003e - `--remote-debugging-port` exposes full browser control on localhost. Any local process can connect. Only use on trusted machines and close Chrome when done.\n\u003e - State files contain session tokens in plaintext. Add them to `.gitignore` and delete when no longer needed. For encryption at rest, set `AGENT_BROWSER_ENCRYPTION_KEY` (see [State Encryption](#state-encryption)).\n\nFor full details on login flows, OAuth, 2FA, cookie-based auth, and the auth vault, see the [Authentication](docs/src/app/sessions/page.mdx) docs.\n\n## Sessions\n\nRun multiple isolated browser instances:\n\n```bash\n# Different sessions\nagent-browser --session agent1 open site-a.com\nagent-browser --session agent2 open site-b.com\n\n# Or via environment variable\nAGENT_BROWSER_SESSION=agent1 agent-browser click \"#btn\"\n\n# List active sessions\nagent-browser session list\n# Output:\n# Active sessions:\n# -\u003e default\n#    agent1\n\n# Show current session\nagent-browser session\n```\n\nEach session has its own:\n\n- Browser instance\n- Cookies and storage\n- Navigation history\n- Authentication state\n\n## Chrome Profile Reuse\n\nThe fastest way to use your existing login state: pass a Chrome profile name to `--profile`:\n\n```bash\n# List available Chrome profiles\nagent-browser profiles\n\n# Reuse your default Chrome profile's login state\nagent-browser --profile Default open https://gmail.com\n\n# Use a named profile (by display name or directory name)\nagent-browser --profile \"Work\" open https://app.example.com\n\n# Or via environment variable\nAGENT_BROWSER_PROFILE=Default agent-browser open https://gmail.com\n```\n\nThis copies your Chrome profile to a temp directory (read-only snapshot, no changes to your original profile), so the browser launches with your existing cookies and sessions.\n\n\u003e **Note:** On Windows, close Chrome before using `--profile \u003cname\u003e` if Chrome is running, as some profile files may be locked.\n\n## Persistent Profiles\n\nFor a persistent custom profile directory that stores state across browser restarts, pass a path to `--profile`:\n\n```bash\n# Use a persistent profile directory\nagent-browser --profile ~/.myapp-profile open myapp.com\n\n# Login once, then reuse the authenticated session\nagent-browser --profile ~/.myapp-profile open myapp.com/dashboard\n\n# Or via environment variable\nAGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com\n```\n\nThe profile directory stores:\n\n- Cookies and localStorage\n- IndexedDB data\n- Service workers\n- Browser cache\n- Login sessions\n\n**Tip**: Use different profile paths for different projects to keep their browser state isolated.\n\n## Session Persistence\n\nAlternatively, use `--session-name` to automatically save and restore cookies and localStorage across browser restarts:\n\n```bash\n# Auto-save/load state for \"twitter\" session\nagent-browser --session-name twitter open twitter.com\n\n# Login once, then state persists automatically\n# State files stored in ~/.agent-browser/sessions/\n\n# Or via environment variable\nexport AGENT_BROWSER_SESSION_NAME=twitter\nagent-browser open twitter.com\n```\n\n### State Encryption\n\nEncrypt saved session data at rest with AES-256-GCM:\n\n```bash\n# Generate key: openssl rand -hex 32\nexport AGENT_BROWSER_ENCRYPTION_KEY=\u003c64-char-hex-key\u003e\n\n# State files are now encrypted automatically\nagent-browser --session-name secure open example.com\n```\n\n| Variable                          | Description                                        |\n| --------------------------------- | -------------------------------------------------- |\n| `AGENT_BROWSER_SESSION_NAME`      | Auto-save/load state persistence name              |\n| `AGENT_BROWSER_ENCRYPTION_KEY`    | 64-char hex key for AES-256-GCM encryption         |\n| `AGENT_BROWSER_STATE_EXPIRE_DAYS` | Auto-delete states older than N days (default: 30) |\n\n## Security\n\nagent-browser includes security features for safe AI agent deployments. All features are opt-in -- existing workflows are unaffected until you explicitly enable a feature:\n\n- **Authentication Vault** -- Store credentials locally (always encrypted), reference by name. The LLM never sees passwords. `auth login` navigates with `load` and then waits for login form selectors to appear (SPA-friendly, timeout follows the default action timeout). A key is auto-generated at `~/.agent-browser/.encryption-key` if `AGENT_BROWSER_ENCRYPTION_KEY` is not set: `echo \"pass\" | agent-browser auth save github --url https://github.com/login --username user --password-stdin` then `agent-browser auth login github`\n- **Content Boundary Markers** -- Wrap page output in delimiters so LLMs can distinguish tool output from untrusted content: `--content-boundaries`\n- **Domain Allowlist** -- Restrict navigation to trusted domains (wildcards like `*.example.com` also match the bare domain): `--allowed-domains \"example.com,*.example.com\"`. Sub-resource requests (scripts, images, fetch) and WebSocket/EventSource connections to non-allowed domains are also blocked. Include any CDN domains your target pages depend on (e.g., `*.cdn.example.com`).\n- **Action Policy** -- Gate destructive actions with a static policy file: `--action-policy ./policy.json`\n- **Action Confirmation** -- Require explicit approval for sensitive action categories: `--confirm-actions eval,download`\n- **Output Length Limits** -- Prevent context flooding: `--max-output 50000`\n\n| Variable                            | Description                              |\n| ----------------------------------- | ---------------------------------------- |\n| `AGENT_BROWSER_CONTENT_BOUNDARIES`  | Wrap page output in boundary markers     |\n| `AGENT_BROWSER_MAX_OUTPUT`          | Max characters for page output           |\n| `AGENT_BROWSER_ALLOWED_DOMAINS`     | Comma-separated allowed domain patterns  |\n| `AGENT_BROWSER_ACTION_POLICY`       | Path to action policy JSON file          |\n| `AGENT_BROWSER_CONFIRM_ACTIONS`     | Action categories requiring confirmation |\n| `AGENT_BROWSER_CONFIRM_INTERACTIVE` | Enable interactive confirmation prompts  |\n\nSee [Security documentation](https://agent-browser.dev/security) for details.\n\n## Snapshot Options\n\nThe `snapshot` command supports filtering to reduce output size:\n\n```bash\nagent-browser snapshot                    # Full accessibility tree\nagent-browser snapshot -i                 # Interactive elements only (buttons, inputs, links)\nagent-browser snapshot -i --urls          # Interactive elements with link URLs\nagent-browser snapshot -c                 # Compact (remove empty structural elements)\nagent-browser snapshot -d 3               # Limit depth to 3 levels\nagent-browser snapshot -s \"#main\"         # Scope to CSS selector\nagent-browser snapshot -i -c -d 5         # Combine options\n```\n\n| Option                 | Description                                                             |\n| ---------------------- | ----------------------------------------------------------------------- |\n| `-i, --interactive`    | Only show interactive elements (buttons, links, inputs)                 |\n| `-u, --urls`           | Include href URLs for link elements                                     |\n| `-c, --compact`        | Remove empty structural elements                                        |\n| `-d, --depth \u003cn\u003e`      | Limit tree depth                                                        |\n| `-s, --selector \u003csel\u003e` | Scope to CSS selector                                                   |\n\n## Annotated Screenshots\n\nThe `--annotate` flag overlays numbered labels on interactive elements in the screenshot. Each label `[N]` corresponds to ref `@eN`, so the same refs work for both visual and text-based workflows.\n\nAnnotated screenshots are supported on the CDP-backed browser path (Chrome/Lightpanda). The Safari/WebDriver backend does not yet support `--annotate`.\n\n```bash\nagent-browser screenshot --annotate\n# -\u003e Screenshot saved to /tmp/screenshot-2026-02-17T12-00-00-abc123.png\n#    [1] @e1 button \"Submit\"\n#    [2] @e2 link \"Home\"\n#    [3] @e3 textbox \"Email\"\n```\n\nAfter an annotated screenshot, refs are cached so you can immediately interact with elements:\n\n```bash\nagent-browser screenshot --annotate ./page.png\nagent-browser click @e2     # Click the \"Home\" link labeled [2]\n```\n\nThis is useful for multimodal AI models that can reason about visual layout, unlabeled icon buttons, canvas elements, or visual state that the text accessibility tree cannot capture.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--session \u003cname\u003e` | Use isolated session (or `AGENT_BROWSER_SESSION` env) |\n| `--session-name \u003cname\u003e` | Auto-save/restore session state (or `AGENT_BROWSER_SESSION_NAME` env) |\n| `--profile \u003cname\\|path\u003e` | Chrome profile name or persistent directory path (or `AGENT_BROWSER_PROFILE` env) |\n| `--state \u003cpath\u003e` | Load storage state from JSON file (or `AGENT_BROWSER_STATE` env) |\n| `--headers \u003cjson\u003e` | Set HTTP headers scoped to the URL's origin |\n| `--executable-path \u003cpath\u003e` | Custom browser executable (or `AGENT_BROWSER_EXECUTABLE_PATH` env) |\n| `--extension \u003cpath\u003e` | Load browser extension (repeatable; or `AGENT_BROWSER_EXTENSIONS` env) |\n| `--args \u003cargs\u003e` | Browser launch args, comma or newline separated (or `AGENT_BROWSER_ARGS` env) |\n| `--user-agent \u003cua\u003e` | Custom User-Agent string (or `AGENT_BROWSER_USER_AGENT` env) |\n| `--proxy \u003curl\u003e` | Proxy server URL with optional auth (or `AGENT_BROWSER_PROXY` env) |\n| `--proxy-bypass \u003chosts\u003e` | Hosts to bypass proxy (or `AGENT_BROWSER_PROXY_BYPASS` env) |\n| `--ignore-https-errors` | Ignore HTTPS certificate errors (useful for self-signed certs) |\n| `--allow-file-access` | Allow file:// URLs to access local files (Chromium only) |\n| `-p, --provider \u003cname\u003e` | Cloud browser provider (or `AGENT_BROWSER_PROVIDER` env) |\n| `--device \u003cname\u003e` | iOS device name, e.g. \"iPhone 15 Pro\" (or `AGENT_BROWSER_IOS_DEVICE` env) |\n| `--json` | JSON output (for agents) |\n| `--annotate` | Annotated screenshot with numbered element labels (or `AGENT_BROWSER_ANNOTATE` env) |\n| `--screenshot-dir \u003cpath\u003e` | Default screenshot output directory (or `AGENT_BROWSER_SCREENSHOT_DIR` env) |\n| `--screenshot-quality \u003cn\u003e` | JPEG quality 0-100 (or `AGENT_BROWSER_SCREENSHOT_QUALITY` env) |\n| `--screenshot-format \u003cfmt\u003e` | Screenshot format: `png`, `jpeg` (or `AGENT_BROWSER_SCREENSHOT_FORMAT` env) |\n| `--headed` | Show browser window (not headless) (or `AGENT_BROWSER_HEADED` env) |\n| `--cdp \u003cport\\|url\u003e` | Connect via Chrome DevTools Protocol (port or WebSocket URL) |\n| `--auto-connect` | Auto-discover and connect to running Chrome (or `AGENT_BROWSER_AUTO_CONNECT` env) |\n| `--color-scheme \u003cscheme\u003e` | Color scheme: `dark`, `light`, `no-preference` (or `AGENT_BROWSER_COLOR_SCHEME` env) |\n| `--download-path \u003cpath\u003e` | Default download directory (or `AGENT_BROWSER_DOWNLOAD_PATH` env) |\n| `--content-boundaries` | Wrap page output in boundary markers for LLM safety (or `AGENT_BROWSER_CONTENT_BOUNDARIES` env) |\n| `--max-output \u003cchars\u003e` | Truncate page output to N characters (or `AGENT_BROWSER_MAX_OUTPUT` env) |\n| `--allowed-domains \u003clist\u003e` | Comma-separated allowed domain patterns (or `AGENT_BROWSER_ALLOWED_DOMAINS` env) |\n| `--action-policy \u003cpath\u003e` | Path to action policy JSON file (or `AGENT_BROWSER_ACTION_POLICY` env) |\n| `--confirm-actions \u003clist\u003e` | Action categories requiring confirmation (or `AGENT_BROWSER_CONFIRM_ACTIONS` env) |\n| `--confirm-interactive` | Interactive confirmation prompts; auto-denies if stdin is not a TTY (or `AGENT_BROWSER_CONFIRM_INTERACTIVE` env) |\n| `--engine \u003cname\u003e` | Browser engine: `chrome` (default), `lightpanda` (or `AGENT_BROWSER_ENGINE` env) |\n| `--no-auto-dialog` | Disable automatic dismissal of `alert`/`beforeunload` dialogs (or `AGENT_BROWSER_NO_AUTO_DIALOG` env) |\n| `--model \u003cname\u003e` | AI model for chat command (or `AI_GATEWAY_MODEL` env) |\n| `-v`, `--verbose` | Show tool commands and their raw output (chat) |\n| `-q`, `--quiet` | Show only AI text responses, hide tool calls (chat) |\n| `--config \u003cpath\u003e` | Use a custom config file (or `AGENT_BROWSER_CONFIG` env) |\n| `--debug` | Debug output |\n\n## Observability Dashboard\n\nMonitor agent-browser sessions in real time with a local web dashboard showing a live viewport and command activity feed.\n\n```bash\n# Start the dashboard server (runs in background on port 4848)\nagent-browser dashboard start\nagent-browser dashboard start --port 8080   # Custom port\n\n# All sessions are automatically visible in the dashboard\nagent-browser open example.com\n\n# Stop the dashboard\nagent-browser dashboard stop\n```\n\nThe dashboard runs as a standalone background process on port 4848, independent of browser sessions. It stays available even when no sessions are running. All sessions automatically stream to the dashboard.\n\nThe dashboard displays:\n- **Live viewport** -- real-time JPEG frames from the browser\n- **Activity feed** -- chronological command/result stream with timing and expandable details\n- **Console output** -- browser console messages (log, warn, error)\n- **Session creation** -- create new sessions from the UI with local engines (Chrome, Lightpanda) or cloud providers (AgentCore, Browserbase, Browserless, Browser Use, Kernel)\n- **AI Chat** -- chat with an AI assistant directly in the dashboard (requires Vercel AI Gateway configuration)\n\n### AI Chat\n\nThe dashboard includes an optional AI chat panel powered by the Vercel AI Gateway. The same functionality is available directly from the CLI via the `chat` command. Set these environment variables to enable AI chat:\n\n```bash\nexport AI_GATEWAY_API_KEY=gw_your_key_here\nexport AI_GATEWAY_MODEL=anthropic/claude-sonnet-4.6           # optional, this is the default\nexport AI_GATEWAY_URL=https://ai-gateway.vercel.sh           # optional, this is the default\n```\n\n**CLI usage:**\n\n```bash\nagent-browser chat \"open google.com and search for cats\"     # Single-shot\nagent-browser chat                                           # Interactive REPL\nagent-browser -q chat \"summarize this page\"                  # Quiet mode (text only)\nagent-browser -v chat \"fill in the login form\"               # Verbose (show command output)\nagent-browser --model openai/gpt-4o chat \"take a screenshot\" # Override model\n```\n\nThe `chat` command translates natural language instructions into agent-browser commands, executes them, and streams the AI response. In interactive mode, type `quit` to exit. Use `--json` for structured output suitable for agent consumption.\n\n**Dashboard usage:**\n\nThe Chat tab is always visible in the dashboard. When `AI_GATEWAY_API_KEY` is set, the Rust server proxies requests to the gateway and streams responses back using the Vercel AI SDK's UI Message Stream protocol. Without the key, sending a message shows an error inline.\n\n## Configuration\n\nCreate an `agent-browser.json` file to set persistent defaults instead of repeating flags on every command.\n\n**Locations (lowest to highest priority):**\n\n1. `~/.agent-browser/config.json` -- user-level defaults\n2. `./agent-browser.json` -- project-level overrides (in working directory)\n3. `AGENT_BROWSER_*` environment variables override config file values\n4. CLI flags override everything\n\n**Example `agent-browser.json`:**\n\n```json\n{\n  \"headed\": true,\n  \"proxy\": \"http://localhost:8080\",\n  \"profile\": \"./browser-data\",\n  \"userAgent\": \"my-agent/1.0\",\n  \"ignoreHttpsErrors\": true\n}\n```\n\nUse `--config \u003cpath\u003e` or `AGENT_BROWSER_CONFIG` to load a specific config file instead of the defaults:\n\n```bash\nagent-browser --config ./ci-config.json open example.com\nAGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com\n```\n\nAll options from the table above can be set in the config file using camelCase keys (e.g., `--executable-path` becomes `\"executablePath\"`, `--proxy-bypass` becomes `\"proxyBypass\"`). Unknown keys are ignored for forward compatibility.\n\nA [JSON Schema](agent-browser.schema.json) is available for IDE autocomplete and validation. Add a `$schema` key to your config file to enable it:\n\n```json\n{\n  \"$schema\": \"https://agent-browser.dev/schema.json\",\n  \"headed\": true\n}\n```\n\nBoolean flags accept an optional `true`/`false` value to override config settings. For example, `--headed false` disables `\"headed\": true` from config. A bare `--headed` is equivalent to `--headed true`.\n\nAuto-discovered config files that are missing are silently ignored. If `--config \u003cpath\u003e` points to a missing or invalid file, agent-browser exits with an error. Extensions from user and project configs are merged (concatenated), not replaced.\n\n\u003e **Tip:** If your project-level `agent-browser.json` contains environment-specific values (paths, proxies), consider adding it to `.gitignore`.\n\n## Default Timeout\n\nThe default timeout for standard operations (clicks, waits, fills, etc.) is 25 seconds. This is intentionally below the CLI's 30-second IPC read timeout so that the daemon returns a proper error instead of the CLI timing out with EAGAIN.\n\nOverride the default timeout via environment variable:\n\n```bash\n# Set a longer timeout for slow pages (in milliseconds)\nexport AGENT_BROWSER_DEFAULT_TIMEOUT=45000\n```\n\n\u003e **Note:** Setting this above 30000 (30s) may cause EAGAIN errors on slow operations because the CLI's read timeout will expire before the daemon responds. The CLI retries transient errors automatically, but response times will increase.\n\n| Variable                        | Description                              |\n| ------------------------------- | ---------------------------------------- |\n| `AGENT_BROWSER_DEFAULT_TIMEOUT` | Default operation timeout in ms (default: 25000) |\n\n## Selectors\n\n### Refs (Recommended for AI)\n\nRefs provide deterministic element selection from snapshots:\n\n```bash\n# 1. Get snapshot with refs\nagent-browser snapshot\n# Output:\n# - heading \"Example Domain\" [ref=e1] [level=1]\n# - button \"Submit\" [ref=e2]\n# - textbox \"Email\" [ref=e3]\n# - link \"Learn more\" [ref=e4]\n\n# 2. Use refs to interact\nagent-browser click @e2                   # Click the button\nagent-browser fill @e3 \"test@example.com\" # Fill the textbox\nagent-browser get text @e1                # Get heading text\nagent-browser hover @e4                   # Hover the link\n```\n\n**Why use refs?**\n\n- **Deterministic**: Ref points to exact element from snapshot\n- **Fast**: No DOM re-query needed\n- **AI-friendly**: Snapshot + ref workflow is optimal for LLMs\n\n### CSS Selectors\n\n```bash\nagent-browser click \"#id\"\nagent-browser click \".class\"\nagent-browser click \"div \u003e button\"\n```\n\n### Text \u0026 XPath\n\n```bash\nagent-browser click \"text=Submit\"\nagent-browser click \"xpath=//button\"\n```\n\n### Semantic Locators\n\n```bash\nagent-browser find role button click --name \"Submit\"\nagent-browser find label \"Email\" fill \"test@test.com\"\n```\n\n## Agent Mode\n\nUse `--json` for machine-readable output:\n\n```bash\nagent-browser snapshot --json\n# Returns: {\"success\":true,\"data\":{\"snapshot\":\"...\",\"refs\":{\"e1\":{\"role\":\"heading\",\"name\":\"Title\"},...}}}\n\nagent-browser get text @e1 --json\nagent-browser is visible @e2 --json\n```\n\n### Optimal AI Workflow\n\n```bash\n# 1. Navigate and get snapshot\nagent-browser open example.com\nagent-browser snapshot -i --json   # AI parses tree and refs\n\n# 2. AI identifies target refs from snapshot\n# 3. Execute actions using refs\nagent-browser click @e2\nagent-browser fill @e3 \"input text\"\n\n# 4. Get new snapshot if page changed\nagent-browser snapshot -i --json\n```\n\n### Command Chaining\n\nCommands can be chained with `\u0026\u0026` in a single shell invocation. The browser persists via a background daemon, so chaining is safe and more efficient:\n\n```bash\n# Open, wait for load, and snapshot in one call\nagent-browser open example.com \u0026\u0026 agent-browser wait --load networkidle \u0026\u0026 agent-browser snapshot -i\n\n# Chain multiple interactions\nagent-browser fill @e1 \"user@example.com\" \u0026\u0026 agent-browser fill @e2 \"pass\" \u0026\u0026 agent-browser click @e3\n\n# Navigate and screenshot\nagent-browser open example.com \u0026\u0026 agent-browser wait --load networkidle \u0026\u0026 agent-browser screenshot page.png\n```\n\nUse `\u0026\u0026` 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).\n\n## Headed Mode\n\nShow the browser window for debugging:\n\n```bash\nagent-browser open example.com --headed\n```\n\nThis opens a visible browser window instead of running headless.\n\n\u003e **Note:** Browser extensions work in both headed and headless mode (Chrome's `--headless=new`).\n\n## Authenticated Sessions\n\nUse `--headers` to set HTTP headers for a specific origin, enabling authentication without login flows:\n\n```bash\n# Headers are scoped to api.example.com only\nagent-browser open api.example.com --headers '{\"Authorization\": \"Bearer \u003ctoken\u003e\"}'\n\n# Requests to api.example.com include the auth header\nagent-browser snapshot -i --json\nagent-browser click @e2\n\n# Navigate to another domain - headers are NOT sent (safe!)\nagent-browser open other-site.com\n```\n\nThis is useful for:\n\n- **Skipping login flows** - Authenticate via headers instead of UI\n- **Switching users** - Start new sessions with different auth tokens\n- **API testing** - Access protected endpoints directly\n- **Security** - Headers are scoped to the origin, not leaked to other domains\n\nTo set headers for multiple origins, use `--headers` with each `open` command:\n\n```bash\nagent-browser open api.example.com --headers '{\"Authorization\": \"Bearer token1\"}'\nagent-browser open api.acme.com --headers '{\"Authorization\": \"Bearer token2\"}'\n```\n\nFor global headers (all domains), use `set headers`:\n\n```bash\nagent-browser set headers '{\"X-Custom-Header\": \"value\"}'\n```\n\n## Custom Browser Executable\n\nUse a custom browser executable instead of the bundled Chromium. This is useful for:\n\n- **Serverless deployment**: Use lightweight Chromium builds like `@sparticuz/chromium` (~50MB vs ~684MB)\n- **System browsers**: Use an existing Chrome/Chromium installation\n- **Custom builds**: Use modified browser builds\n\n### CLI Usage\n\n```bash\n# Via flag\nagent-browser --executable-path /path/to/chromium open example.com\n\n# Via environment variable\nAGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com\n```\n\n### Serverless (Vercel)\n\nRun agent-browser + Chrome in an ephemeral Vercel Sandbox microVM. No external server needed:\n\n```typescript\nimport { Sandbox } from \"@vercel/sandbox\";\n\nconst sandbox = await Sandbox.create({ runtime: \"node24\" });\nawait sandbox.runCommand(\"agent-browser\", [\"open\", \"https://example.com\"]);\nconst result = await sandbox.runCommand(\"agent-browser\", [\"screenshot\", \"--json\"]);\nawait sandbox.stop();\n```\n\nSee the [environments example](examples/environments/) for a working demo with a UI and deploy-to-Vercel button.\n\n### Serverless (AWS Lambda)\n\n```typescript\nimport chromium from '@sparticuz/chromium';\nimport { execSync } from 'child_process';\n\nexport async function handler() {\n  const executablePath = await chromium.executablePath();\n  const result = execSync(\n    `AGENT_BROWSER_EXECUTABLE_PATH=${executablePath} agent-browser open https://example.com \u0026\u0026 agent-browser snapshot -i --json`,\n    { encoding: 'utf-8' }\n  );\n  return JSON.parse(result);\n}\n```\n\n## Local Files\n\nOpen and interact with local files (PDFs, HTML, etc.) using `file://` URLs:\n\n```bash\n# Enable file access (required for JavaScript to access local files)\nagent-browser --allow-file-access open file:///path/to/document.pdf\nagent-browser --allow-file-access open file:///path/to/page.html\n\n# Take screenshot of a local PDF\nagent-browser --allow-file-access open file:///Users/me/report.pdf\nagent-browser screenshot report.png\n```\n\nThe `--allow-file-access` flag adds Chromium flags (`--allow-file-access-from-files`, `--allow-file-access`) that allow `file://` URLs to:\n\n- Load and render local files\n- Access other local files via JavaScript (XHR, fetch)\n- Load local resources (images, scripts, stylesheets)\n\n**Note:** This flag only works with Chromium. For security, it's disabled by default.\n\n## CDP Mode\n\nConnect to an existing browser via Chrome DevTools Protocol:\n\n```bash\n# Start Chrome with: google-chrome --remote-debugging-port=9222\n\n# Connect once, then run commands without --cdp\nagent-browser connect 9222\nagent-browser snapshot\nagent-browser tab\nagent-browser close\n\n# Or pass --cdp on each command\nagent-browser --cdp 9222 snapshot\n\n# Connect to remote browser via WebSocket URL\nagent-browser --cdp \"wss://your-browser-service.com/cdp?token=...\" snapshot\n```\n\nThe `--cdp` flag accepts either:\n\n- A port number (e.g., `9222`) for local connections via `http://localhost:{port}`\n- A full WebSocket URL (e.g., `wss://...` or `ws://...`) for remote browser services\n\nThis enables control of:\n\n- Electron apps\n- Chrome/Chromium instances with remote debugging\n- WebView2 applications\n- Any browser exposing a CDP endpoint\n\n### Auto-Connect\n\nUse `--auto-connect` to automatically discover and connect to a running Chrome instance without specifying a port:\n\n```bash\n# Auto-discover running Chrome with remote debugging\nagent-browser --auto-connect open example.com\nagent-browser --auto-connect snapshot\n\n# Or via environment variable\nAGENT_BROWSER_AUTO_CONNECT=1 agent-browser snapshot\n```\n\nAuto-connect discovers Chrome by:\n\n1. Reading Chrome's `DevToolsActivePort` file from the default user data directory\n2. Falling back to probing common debugging ports (9222, 9229)\n3. If HTTP-based discovery (`/json/version`, `/json/list`) fails, falling back to a direct WebSocket connection\n\nThis is useful when:\n\n- Chrome 144+ has remote debugging enabled via `chrome://inspect/#remote-debugging` (which uses a dynamic port)\n- You want a zero-configuration connection to your existing browser\n- You don't want to track which port Chrome is using\n\n## Streaming (Browser Preview)\n\nStream the browser viewport via WebSocket for live preview or \"pair browsing\" where a human can watch and interact alongside an AI agent.\n\n### Streaming\n\nEvery session automatically starts a WebSocket stream server on an OS-assigned port. Use `stream status` to see the bound port and connection state:\n\n```bash\nagent-browser stream status\n```\n\nTo bind to a specific port, set `AGENT_BROWSER_STREAM_PORT`:\n\n```bash\nAGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com\n```\n\nYou can also manage streaming at runtime with `stream enable`, `stream disable`, and `stream status`:\n\n```bash\nagent-browser stream enable --port 9223   # Re-enable on a specific port\nagent-browser stream disable              # Stop streaming for the session\n```\n\nThe WebSocket server streams the browser viewport and accepts input events.\n\n### WebSocket Protocol\n\nConnect to `ws://localhost:9223` to receive frames and send input:\n\n**Receive frames:**\n\n```json\n{\n  \"type\": \"frame\",\n  \"data\": \"\u003cbase64-encoded-jpeg\u003e\",\n  \"metadata\": {\n    \"deviceWidth\": 1280,\n    \"deviceHeight\": 720,\n    \"pageScaleFactor\": 1,\n    \"offsetTop\": 0,\n    \"scrollOffsetX\": 0,\n    \"scrollOffsetY\": 0\n  }\n}\n```\n\n**Send mouse events:**\n\n```json\n{\n  \"type\": \"input_mouse\",\n  \"eventType\": \"mousePressed\",\n  \"x\": 100,\n  \"y\": 200,\n  \"button\": \"left\",\n  \"clickCount\": 1\n}\n```\n\n**Send keyboard events:**\n\n```json\n{\n  \"type\": \"input_keyboard\",\n  \"eventType\": \"keyDown\",\n  \"key\": \"Enter\",\n  \"code\": \"Enter\"\n}\n```\n\n**Send touch events:**\n\n```json\n{\n  \"type\": \"input_touch\",\n  \"eventType\": \"touchStart\",\n  \"touchPoints\": [{ \"x\": 100, \"y\": 200 }]\n}\n```\n\n## Architecture\n\nagent-browser uses a client-daemon architecture:\n\n1. **Rust CLI** - Parses commands, communicates with daemon\n2. **Rust Daemon** - Pure Rust daemon using direct CDP, no Node.js required\n\nThe daemon starts automatically on first command and persists between commands for fast subsequent operations. To auto-shutdown the daemon after a period of inactivity, set `AGENT_BROWSER_IDLE_TIMEOUT_MS` (value in milliseconds). When set, the daemon closes the browser and exits after receiving no commands for the specified duration.\n\n**Browser Engine:** Uses Chrome (from Chrome for Testing) by default. The `--engine` flag selects between `chrome` and `lightpanda`. Supported browsers: Chromium/Chrome (via CDP) and Safari (via WebDriver for iOS).\n\n## Platforms\n\n| Platform    | Binary      |\n| ----------- | ----------- |\n| macOS ARM64 | Native Rust |\n| macOS x64   | Native Rust |\n| Linux ARM64 | Native Rust |\n| Linux x64   | Native Rust |\n| Windows x64 | Native Rust |\n\n## Usage with AI Agents\n\n### Just ask the agent\n\nThe simplest approach -- just tell your agent to use it:\n\n```\nUse agent-browser to test the login flow. Run agent-browser --help to see available commands.\n```\n\nThe `--help` output is comprehensive and most agents can figure it out from there.\n\n### AI Coding Assistants (recommended)\n\nAdd the skill to your AI coding assistant for richer context:\n\n```bash\nnpx skills add vercel-labs/agent-browser\n```\n\nThis works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf. The skill is fetched from the repository, so it stays up to date automatically -- do not copy `SKILL.md` from `node_modules` as it will become stale.\n\n### Claude Code\n\nInstall as a Claude Code skill:\n\n```bash\nnpx skills add vercel-labs/agent-browser\n```\n\nThis adds a thin discovery stub at `.claude/skills/agent-browser/SKILL.md`. The stub is intentionally minimal — it points Claude Code at `agent-browser skills get core` to load the actual workflow content at runtime. This way the instructions always match the installed CLI version instead of going stale between releases.\n\n### AGENTS.md / CLAUDE.md\n\nFor more consistent results, add to your project or global instructions file:\n\n```markdown\n## Browser Automation\n\nUse `agent-browser` for web automation. Run `agent-browser --help` for all commands.\n\nCore workflow:\n\n1. `agent-browser open \u003curl\u003e` - Navigate to page\n2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)\n3. `agent-browser click @e1` / `fill @e2 \"text\"` - Interact using refs\n4. Re-snapshot after page changes\n```\n\n## Integrations\n\n### iOS Simulator\n\nControl real Mobile Safari in the iOS Simulator for authentic mobile web testing. Requires macOS with Xcode.\n\n**Setup:**\n\n```bash\n# Install Appium and XCUITest driver\nnpm install -g appium\nappium driver install xcuitest\n```\n\n**Usage:**\n\n```bash\n# List available iOS simulators\nagent-browser device list\n\n# Launch Safari on a specific device\nagent-browser -p ios --device \"iPhone 16 Pro\" open https://example.com\n\n# Same commands as desktop\nagent-browser -p ios snapshot -i\nagent-browser -p ios tap @e1\nagent-browser -p ios fill @e2 \"text\"\nagent-browser -p ios screenshot mobile.png\n\n# Mobile-specific commands\nagent-browser -p ios swipe up\nagent-browser -p ios swipe down 500\n\n# Close session\nagent-browser -p ios close\n```\n\nOr use environment variables:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=ios\nexport AGENT_BROWSER_IOS_DEVICE=\"iPhone 16 Pro\"\nagent-browser open https://example.com\n```\n\n| Variable                   | Description                                     |\n| -------------------------- | ----------------------------------------------- |\n| `AGENT_BROWSER_PROVIDER`   | Set to `ios` to enable iOS mode                 |\n| `AGENT_BROWSER_IOS_DEVICE` | Device name (e.g., \"iPhone 16 Pro\", \"iPad Pro\") |\n| `AGENT_BROWSER_IOS_UDID`   | Device UDID (alternative to device name)        |\n\n**Supported devices:** All iOS Simulators available in Xcode (iPhones, iPads), plus real iOS devices.\n\n**Note:** The iOS provider boots the simulator, starts Appium, and controls Safari. First launch takes ~30-60 seconds; subsequent commands are fast.\n\n#### Real Device Support\n\nAppium also supports real iOS devices connected via USB. This requires additional one-time setup:\n\n**1. Get your device UDID:**\n\n```bash\nxcrun xctrace list devices\n# or\nsystem_profiler SPUSBDataType | grep -A 5 \"iPhone\\|iPad\"\n```\n\n**2. Sign WebDriverAgent (one-time):**\n\n```bash\n# Open the WebDriverAgent Xcode project\ncd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent\nopen WebDriverAgent.xcodeproj\n```\n\nIn Xcode:\n\n- Select the `WebDriverAgentRunner` target\n- Go to Signing \u0026 Capabilities\n- Select your Team (requires Apple Developer account, free tier works)\n- Let Xcode manage signing automatically\n\n**3. Use with agent-browser:**\n\n```bash\n# Connect device via USB, then:\nagent-browser -p ios --device \"\u003cDEVICE_UDID\u003e\" open https://example.com\n\n# Or use the device name if unique\nagent-browser -p ios --device \"John's iPhone\" open https://example.com\n```\n\n**Real device notes:**\n\n- First run installs WebDriverAgent to the device (may require Trust prompt)\n- Device must be unlocked and connected via USB\n- Slightly slower initial connection than simulator\n- Tests against real Safari performance and behavior\n\n### Browserless\n\n[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.\n\nTo enable Browserless, use the `-p` flag:\n\n```bash\nexport BROWSERLESS_API_KEY=\"your-api-token\"\nagent-browser -p browserless open https://example.com\n```\n\nOr use environment variables for CI/scripts:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=browserless\nexport BROWSERLESS_API_KEY=\"your-api-token\"\nagent-browser open https://example.com\n```\n\nOptional configuration via environment variables:\n\n| Variable                   | Description                                      | Default                                 |\n| -------------------------- | ------------------------------------------------ | --------------------------------------- |\n| `BROWSERLESS_API_URL`      | Base API URL (for custom regions or self-hosted) | `https://production-sfo.browserless.io` |\n| `BROWSERLESS_BROWSER_TYPE` | Type of browser to use (chromium or chrome)      | chromium                                |\n| `BROWSERLESS_TTL`          | Session TTL in milliseconds                      | `300000`                                |\n| `BROWSERLESS_STEALTH`      | Enable stealth mode (`true`/`false`)             | `true`                                  |\n\nWhen enabled, agent-browser connects to a Browserless cloud session instead of launching a local browser. All commands work identically.\n\nGet your API token from the [Browserless Dashboard](https://browserless.io).\n\n### Browserbase\n\n[Browserbase](https://browserbase.com) provides remote browser infrastructure to make deployment of agentic browsing agents easy. Use it when running the agent-browser CLI in an environment where a local browser isn't feasible.\n\nTo enable Browserbase, use the `-p` flag:\n\n```bash\nexport BROWSERBASE_API_KEY=\"your-api-key\"\nagent-browser -p browserbase open https://example.com\n```\n\nOr use environment variables for CI/scripts:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=browserbase\nexport BROWSERBASE_API_KEY=\"your-api-key\"\nagent-browser open https://example.com\n```\n\nWhen enabled, agent-browser connects to a Browserbase session instead of launching a local browser. All commands work identically.\n\nGet your API key from the [Browserbase Dashboard](https://browserbase.com/overview).\n\n### Browser Use\n\n[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.).\n\nTo enable Browser Use, use the `-p` flag:\n\n```bash\nexport BROWSER_USE_API_KEY=\"your-api-key\"\nagent-browser -p browseruse open https://example.com\n```\n\nOr use environment variables for CI/scripts:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=browseruse\nexport BROWSER_USE_API_KEY=\"your-api-key\"\nagent-browser open https://example.com\n```\n\nWhen enabled, agent-browser connects to a Browser Use cloud session instead of launching a local browser. All commands work identically.\n\nGet 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.\n\n### Kernel\n\n[Kernel](https://www.kernel.sh) provides cloud browser infrastructure for AI agents with features like stealth mode and persistent profiles.\n\nTo enable Kernel, use the `-p` flag:\n\n```bash\nexport KERNEL_API_KEY=\"your-api-key\"\nagent-browser -p kernel open https://example.com\n```\n\nOr use environment variables for CI/scripts:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=kernel\nexport KERNEL_API_KEY=\"your-api-key\"\nagent-browser open https://example.com\n```\n\nOptional configuration via environment variables:\n\n| Variable                 | Description                                                                      | Default |\n| ------------------------ | -------------------------------------------------------------------------------- | ------- |\n| `KERNEL_HEADLESS`        | Run browser in headless mode (`true`/`false`)                                    | `false` |\n| `KERNEL_STEALTH`         | Enable stealth mode to avoid bot detection (`true`/`false`)                      | `true`  |\n| `KERNEL_TIMEOUT_SECONDS` | Session timeout in seconds                                                       | `300`   |\n| `KERNEL_PROFILE_NAME`    | Browser profile name for persistent cookies/logins (created if it doesn't exist) | (none)  |\n\nWhen enabled, agent-browser connects to a Kernel cloud session instead of launching a local browser. All commands work identically.\n\n**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.\n\nGet your API key from the [Kernel Dashboard](https://dashboard.onkernel.com).\n\n### AgentCore\n\n[AWS Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) provides cloud browser sessions with SigV4 authentication.\n\nTo enable AgentCore, use the `-p` flag:\n\n```bash\nagent-browser -p agentcore open https://example.com\n```\n\nOr use environment variables for CI/scripts:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=agentcore\nagent-browser open https://example.com\n```\n\nCredentials are automatically resolved from environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) or the AWS CLI (`aws configure export-credentials`), which supports SSO, profiles, and IAM roles.\n\nOptional configuration via environment variables:\n\n| Variable                   | Description                                                          | Default          |\n| -------------------------- | -------------------------------------------------------------------- | ---------------- |\n| `AGENTCORE_REGION`         | AWS region for the AgentCore endpoint                                | `us-east-1`      |\n| `AGENTCORE_BROWSER_ID`     | Browser identifier                                                   | `aws.browser.v1` |\n| `AGENTCORE_PROFILE_ID`     | Browser profile for persistent state (cookies, localStorage)         | (none)           |\n| `AGENTCORE_SESSION_TIMEOUT`| Session timeout in seconds                                           | `3600`           |\n| `AWS_PROFILE`              | AWS CLI profile for credential resolution                            | `default`        |\n\n**Browser profiles:** When `AGENTCORE_PROFILE_ID` is set, browser state (cookies, localStorage) is persisted across sessions automatically.\n\nWhen enabled, agent-browser connects to an AgentCore cloud browser session instead of launching a local browser. All commands work identically.\n\n## License\n\nApache-2.0\n","funding_links":[],"categories":["Skills Catalog","Rust","AI应用","Skills \u0026 Plugins","\u003ca name=\"Rust\"\u003e\u003c/a\u003eRust","Development Tools","Tools"],"sub_categories":["Agent (45)","Agent Web Interaction"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvercel-labs%2Fagent-browser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvercel-labs%2Fagent-browser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvercel-labs%2Fagent-browser/lists"}