vercel-labs/agent-browser

Maintainer? Show your league in your README

Card: your league's emblem, from Copper to Legendary

[![bestofgithub](https://bestofgithub.dev/badge/vercel-labs/agent-browser.svg?style=card)](https://bestofgithub.dev/repo/vercel-labs/agent-browser)

Flat: fits beside your other badges

[![bestofgithub](https://bestofgithub.dev/badge/vercel-labs/agent-browser.svg)](https://bestofgithub.dev/repo/vercel-labs/agent-browser)

Loading README…

Approach	Best for	Flag / Env
Chrome profile reuse	Reuse your existing Chrome login state (cookies, sessions) with zero setup	`--profile <name>` / `AGENT_BROWSER_PROFILE`
Persistent profile	Full browser state (cookies, IndexedDB, service workers, cache) across restarts	`--profile <path>` / `AGENT_BROWSER_PROFILE`
Session persistence	Auto-save/restore cookies + localStorage from a stable session key	`--session <id> --restore` / `AGENT_BROWSER_RESTORE`
Import from your browser	Grab auth from a Chrome session you already logged into	`--auto-connect` + `state save`
State file	Load a previously saved state JSON on launch	`--state <path>` / `AGENT_BROWSER_STATE`
Auth vault	Store credentials locally (encrypted), login by name	`auth save` / `auth login`

Variable	Description
`AGENT_BROWSER_RESTORE`	Auto-save/load state persistence name
`AGENT_BROWSER_RESTORE_SAVE`	Restore save policy: `auto`, `always`, or `never`
`AGENT_BROWSER_AUTOSAVE_INTERVAL_MS`	Min ms between periodic autosaves (default: 30000, 0 disables)
`AGENT_BROWSER_NAMESPACE`	Namespace for daemon sockets and restore state
`AGENT_BROWSER_SESSION_NAME`	Legacy 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)

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; requires a fresh controllable browser context without profile/session startup args, restore/state replay, or direct-page provider plugins
`AGENT_BROWSER_ACTION_POLICY`	Path to action policy JSON file
`AGENT_BROWSER_CONFIRM_ACTIONS`	Action categories requiring confirmation
`AGENT_BROWSER_CONFIRM_INTERACTIVE`	Enable interactive confirmation prompts
`AGENT_BROWSER_PLUGINS`	JSON plugin registry override

Option	Description
`-i, --interactive`	Only show interactive elements (buttons, links, inputs)
`-u, --urls`	Include href URLs for link elements
`-c, --compact`	Remove empty structural elements
`-d, --depth <n>`	Limit tree depth
`-s, --selector <sel>`	Scope to CSS selector
`--delta`	Return full state once, then `unchanged` or a structural JSON delta
`--full`	Force full state and update the delta baseline

Option	Description
`--session <name>`	Use isolated session (or `AGENT_BROWSER_SESSION` env)
`--restore [name]`	Auto-save/restore session state. Bare `--restore` uses `--session` as the key
`--restore-save <policy>`	Restore save policy: `auto`, `always`, or `never`
`--restore-check-url <glob>`	Validate restored state against a URL pattern
`--restore-check-text <text>`	Validate restored state against page text
`--restore-check-fn <js>`	Validate restored state against a truthy JavaScript expression
`--namespace <name>`	Isolate daemon sockets and restore-state directories
`--session-name <name>`	Legacy alias for restore persistence key
`--profile <name\|path>`	Chrome profile name or persistent directory path (or `AGENT_BROWSER_PROFILE` env)
`--state <path>`	Load storage state from JSON file (or `AGENT_BROWSER_STATE` env)
`--headers <json>`	Set HTTP headers scoped to the URL's origin
`--executable-path <path>`	Custom browser executable (or `AGENT_BROWSER_EXECUTABLE_PATH` env)
`--extension <path>`	Load browser extension (repeatable; or `AGENT_BROWSER_EXTENSIONS` env)
`--init-script <path>`	Register a page init script before the first navigation (repeatable; or `AGENT_BROWSER_INIT_SCRIPTS` env)
`--enable <feature>`	Built-in init scripts: `react-devtools` (repeatable or comma-list; or `AGENT_BROWSER_ENABLE` env)
`--args <args>`	Browser launch args, newline separated, or comma separated before another flag. Commas inside a value such as `--disable-features=A,B` are kept (or `AGENT_BROWSER_ARGS` env)
`--user-agent <ua>`	Custom User-Agent string (or `AGENT_BROWSER_USER_AGENT` env)
`--proxy <url>`	Proxy server URL with optional auth (or `AGENT_BROWSER_PROXY` env)
`--proxy-bypass <hosts>`	Hosts to bypass proxy (or `AGENT_BROWSER_PROXY_BYPASS` env)
`--ignore-https-errors`	Ignore HTTPS certificate errors (useful for self-signed certs)
`--ca-cert <path>`	Trust a CA certificate or PEM bundle for the CLI's own HTTPS requests on every platform, and for locally launched Chromium on Linux; later commands in the same running session retain it when omitted (or `AGENT_BROWSER_CA_CERT` env)
`--no-ca-cert`	Clear CA trust retained by the running browser session (or `AGENT_BROWSER_CLEAR_CA_CERT`)
`--use-system-ca`	Use the operating system trust store for the CLI's own HTTPS requests: `read`, `install`, `upgrade`, `doctor` (or `AGENT_BROWSER_USE_SYSTEM_CA` env)
`--allow-file-access`	Allow file:// URLs to access local files (Chromium only)
`--hide-scrollbars <bool>`	Hide native scrollbars in headless Chromium screenshots, enabled by default (or `AGENT_BROWSER_HIDE_SCROLLBARS` env)
`-p, --provider <name>`	Browser provider, including configured `browser.provider` plugins (or `AGENT_BROWSER_PROVIDER` env)
`--device <name>`	iOS device name, e.g. "iPhone 15 Pro" (or `AGENT_BROWSER_IOS_DEVICE` env)
`--json`	JSON output (for agents)
`--annotate`	Annotated screenshot with numbered element labels (or `AGENT_BROWSER_ANNOTATE` env)
`--if-changed`	Recommended for repeated captures: skip unchanged images to save tokens (history is per tab and scope)
`--threshold <0-1>`	Maximum changed-pixel ratio treated as unchanged; implies `--if-changed`
`--screenshot-dir <path>`	Default screenshot output directory (or `AGENT_BROWSER_SCREENSHOT_DIR` env)
`--screenshot-quality <n>`	JPEG quality 0-100 (or `AGENT_BROWSER_SCREENSHOT_QUALITY` env)
`--screenshot-format <fmt>`	Screenshot format: `png`, `jpeg` (or `AGENT_BROWSER_SCREENSHOT_FORMAT` env)
`--headed`	Show browser window on the interactive desktop (or `AGENT_BROWSER_HEADED` env)
`--webgpu`	Enable WebGPU; SwiftShader software Vulkan on Linux, no GPU required (or `AGENT_BROWSER_WEBGPU` env)
`--no-webmcp`	Disable experimental WebMCP support, which is enabled by default for locally launched Chrome (or `AGENT_BROWSER_NO_WEBMCP` env)
`--cdp <port\|url>`	Connect via Chrome DevTools Protocol (port or WebSocket URL)
`--auto-connect`	Auto-discover and connect to running Chrome (or `AGENT_BROWSER_AUTO_CONNECT` env)
`--pin-tab`	Pin the session to its bound tab; fail with `tab_gone` instead of falling back to another tab (or `AGENT_BROWSER_PIN_TAB` env)
`--no-pin-tab`	Disable a sticky pin previously enabled with `--pin-tab`
`--color-scheme <scheme>`	Color scheme: `dark`, `light`, `no-preference` (or `AGENT_BROWSER_COLOR_SCHEME` env)
`--download-path <path>`	Default download directory (or `AGENT_BROWSER_DOWNLOAD_PATH` env)
`--content-boundaries`	Wrap page output in boundary markers for LLM safety (or `AGENT_BROWSER_CONTENT_BOUNDARIES` env)
`--max-output <chars>`	Truncate page output to N characters (or `AGENT_BROWSER_MAX_OUTPUT` env)
`--allowed-domains <list>`	Comma-separated allowed domain patterns; also disables WebRTC peer connections in supported Chromium sessions and rejects CDP, auto-connect, Chrome profiles, restore/state replay, direct-page provider plugins, unsafe startup `--args`, iOS, and Safari (or `AGENT_BROWSER_ALLOWED_DOMAINS` env)
`--action-policy <path>`	Path to action policy JSON file (or `AGENT_BROWSER_ACTION_POLICY` env)
`--confirm-actions <list>`	Action categories requiring confirmation (or `AGENT_BROWSER_CONFIRM_ACTIONS` env)
`--confirm-interactive`	Interactive confirmation prompts; auto-denies if stdin is not a TTY (or `AGENT_BROWSER_CONFIRM_INTERACTIVE` env)
`--input-mode <mode>`	Session pointer movement: `instant` (default), `smooth`, or `human`
`--idle-timeout <time>`	Shut down the daemon after inactivity (`10s`, `3m`, `1h`, or raw ms). Defaults to `1h`; use `0` to disable (or `AGENT_BROWSER_IDLE_TIMEOUT_MS` env)
`--engine <name>`	Browser engine: `chrome` (default), `lightpanda`, `obscura` (experimental; rejects proxy bypass rules) (or `AGENT_BROWSER_ENGINE` env)
`AGENT_BROWSER_OBSCURA_STEALTH` env	Run the Obscura engine (`--engine obscura`) in stealth mode: consistent fingerprint, tracker blocking
`--no-auto-dialog`	Disable automatic dismissal of `alert`/`beforeunload` dialogs (or `AGENT_BROWSER_NO_AUTO_DIALOG` env)
`--model <name>`	AI model for chat command (or `AI_GATEWAY_MODEL` env)
`-v`, `--verbose`	Show tool commands and their raw output (chat)
`-q`, `--quiet`	Show only AI text responses, hide tool calls (chat)
`--config <path>`	Use a custom config file (or `AGENT_BROWSER_CONFIG` env)
`--debug`	Debug output

Option	Description
`--port <n>`	Dashboard port from 1 to 65535. The default is 4848.
`--allowed-origins <origins>`	Comma-separated exact HTTPS origins allowed to access a reverse-proxied dashboard. Every entry must be valid. Without this option, only loopback origins are accepted.

Variable	Default	Description
`AGENT_BROWSER_STREAM_QUALITY`	`80`	JPEG quality, 0 to 100
`AGENT_BROWSER_STREAM_MAX_WIDTH`	the viewport	Caps frame width in pixels
`AGENT_BROWSER_STREAM_MAX_HEIGHT`	the viewport	Caps frame height in pixels

Platform	Binary
macOS ARM64	Native Rust
macOS x64	Native Rust
Linux ARM64	Native Rust
Linux x64	Native Rust
Windows x64	Native Rust

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

Variable	Description	Default
`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`/`false`)	`true`

Variable	Description
`BROWSER_USE_PROFILE_ID`	Profile UUID for persistent cookies and logins
`BROWSER_USE_PROXY_COUNTRY`	Managed proxy country, or `none`/`direct` to disable proxy
`BROWSER_USE_ENABLE_RECORDING`	Record the Cloud browser session

Variable	Description	Default
`KERNEL_HEADLESS`	Run browser in headless mode (`true`/`false`)	`true`
`KERNEL_STEALTH`	Enable stealth mode to avoid bot detection (`true`/`false`)	`false`
`KERNEL_TIMEOUT_SECONDS`	Session timeout in seconds	`300`
`KERNEL_PROFILE_NAME`	Name of an existing browser profile to load	(none)
`KERNEL_PROFILE_SAVE_CHANGES`	Save session changes back to the profile (`true`/`false`)	`false`

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`

agent-browser

Installation

Global Installation (recommended)

Project Installation (local dependency)

Homebrew (macOS)

Cargo (Rust)

From Source

Linux Dependencies

Updating

Requirements

Quick Start

Traditional Selectors (also supported)

Commands

Core Commands

WebMCP (experimental)

Get Info

Read Agent-Friendly Text

Check State

Find Elements (Semantic Locators)

Wait

Batch Execution

Clipboard

Mouse Control

Browser Settings

Cookies & Storage

Network

Tabs & Windows

Frames

Dialogs

Diff

Debug

Navigation

Pre-navigation setup

React / Web Vitals

Accessibility audits

Init scripts

Setup

Skills

MCP Server

Authentication

Quick summary

Stateful auth vault login

Import auth from your browser

Sessions

Tab pinning

Chrome Profile Reuse

Persistent Profiles

Session Persistence

State Encryption

Security

Plugin System

Snapshot Options

Annotated Screenshots

Options

Observability Dashboard

AI Chat

Configuration

Default Timeout

Selectors

Refs (Recommended for AI)

CSS Selectors

Text & XPath

Semantic Locators

Agent Mode

Optimal AI Workflow

Command Chaining

Headed Mode

WebGPU

Authenticated Sessions

Custom Browser Executable

CLI Usage

Serverless (Vercel)

eve extension

Serverless (AWS Lambda)

Local Files

CDP Mode

Auto-Connect

Streaming (Browser Preview)

Streaming

WebSocket Protocol