agent-browser
Browser automation CLI for AI agents. Fast native Rust CLI.
Installation
Global Installation (recommended)
Installs the native Rust binary:
npm install -g agent-browser
agent-browser install # Download Chrome from Chrome for Testing (first time only)Project Installation (local dependency)
For projects that want to pin the version in package.json:
npm install agent-browser
agent-browser installThen use via package.json scripts or by invoking agent-browser directly.
Homebrew (macOS)
brew install agent-browser
agent-browser install # Download Chrome from Chrome for Testing (first time only)Cargo (Rust)
cargo install agent-browser
agent-browser install # Download Chrome from Chrome for Testing (first time only)From Source
Requires Node.js 24+, pnpm 11+, and Rust.
git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build
pnpm build:native # Requires Rust (https://rustup.rs)
pnpm link --global # Makes agent-browser available globally
agent-browser installLinux Dependencies
On Linux, install system dependencies:
agent-browser install --with-depsThis exits nonzero if the package manager cannot install every required browser library.
Updating
Upgrade to the latest version:
agent-browser upgradeDetects your installation method (npm, Homebrew, or Cargo) and runs the appropriate update command automatically.
Requirements
- Chrome - Run
agent-browser installto download Chrome from 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. - Node.js 24+ and pnpm 11+ - Only needed when building from source.
- Rust - Only needed when building from source (see From Source above).
Quick Start
agent-browser open example.com
agent-browser snapshot # Get accessibility tree with refs
agent-browser click @e2 # Click by ref from snapshot
agent-browser fill @e3 "test@example.com" # Fill by ref
agent-browser get text @e1 # Get text by ref
agent-browser screenshot page.png
agent-browser closeClicks fail early when another element covers the target's click point, for example a consent banner or modal. Dismiss or interact with the reported covering element, then take a fresh snapshot before retrying the original ref.
Headless Chromium screenshots hide native scrollbars for consistent image output. Pass --hide-scrollbars false when launching to keep native scrollbars visible.
Traditional Selectors (also supported)
agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"
agent-browser find role button click --name "Submit"Commands
Core Commands
agent-browser open # Launch browser (no navigation); stays on about:blank
agent-browser open <url> # Launch + navigate to URL (aliases: goto, navigate)
agent-browser read [url] # Fetch agent-readable text, or read rendered active-tab DOM
agent-browser click <sel> # Click element (--new-tab to open in new tab)
agent-browser dblclick <sel> # Double-click element
agent-browser focus <sel> # Focus element
agent-browser type <sel> <text> # Type into element
agent-browser fill <sel> <text> # Clear and fill
agent-browser press <key> # Press key (Enter, Tab, Control+a) (alias: key)
agent-browser keyboard type <text> # Type with real keystrokes (no selector, current focus)
agent-browser keyboard inserttext <text> # Insert text without key events (no selector)
agent-browser keydown <key> # Hold key down
agent-browser keyup <key> # Release key
agent-browser hover <sel> # Hover 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 (alias: scrollinto)
agent-browser drag <src> <tgt> # Drag and drop
agent-browser upload <sel> <files> # Upload files
agent-browser screenshot [path] # Take screenshot (--full for full page, saves to a temporary directory if no path)
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 as PDF
agent-browser snapshot # Accessibility tree with refs (best for AI)
agent-browser eval <js> # Run JavaScript (-b for base64, --stdin for piped input)
agent-browser connect <port> # 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
agent-browser chat "<instruction>" # AI chat: natural language browser control (single-shot)
agent-browser chat # AI chat: interactive REPL modeGet 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 (for DevTools, debugging)
agent-browser get count <sel> # Count matching elements
agent-browser get box <sel> # Get bounding box
agent-browser get styles <sel> # Get computed stylesRead Agent-Friendly Text
agent-browser read
agent-browser read https://example.com/article
agent-browser read https://example.com/article --filter overview
agent-browser read https://example.com/article --outline
agent-browser read https://docs.example.com --llms index --filter auth
agent-browser read https://docs.example.com --llms full --filter auth
agent-browser read example.com/article --require-md
agent-browser read https://example.com/article --jsonread fetches a URL without launching Chrome. Omit the URL to read the rendered DOM of the active tab in the current browser session, including browser auth state and client-side updates. Explicit URL reads send Accept: text/markdown by default, try the same URL with .md appended when the first response is not markdown, walk ancestor paths toward / to find the nearest llms.txt for a matching docs link, print markdown or plain text when available, and fall back to readable text extracted from HTML. --llms and --require-md with no URL use the active tab URL because they depend on HTTP resources. read does not read llms-full.txt unless you ask for it.
Options: --raw prints the response body without HTML extraction, --require-md fails unless the server returns Content-Type: text/markdown, --outline prints a compact heading outline for one page, --llms index prints a compact nearest-ancestor llms.txt link list, --llms full reads the nearest-ancestor llms-full.txt, --filter <text> narrows page sections, llms links/sections, or outline headings, and --timeout <ms> changes the request timeout. Global safeguards such as --allowed-domains, --content-boundaries, and --max-output also apply to read fetches and output.
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 checkedFind Elements (Semantic Locators)
agent-browser find role <role> <action> [value] # By ARIA role
agent-browser find text <text> <action> [value] # By text content
agent-browser find label <label> <action> [value] # By label
agent-browser find placeholder <ph> <action> [value] # By placeholder
agent-browser find alt <text> <action> [value] # By alt text
agent-browser find title <text> <action> [value] # By title attr
agent-browser find testid <id> <action> [value] # By data-testid
agent-browser find first <sel> <action> [value] # First match
agent-browser find last <sel> <action> [value] # Last match
agent-browser find nth <n> <sel> <action> [value] # Nth matchActions: click, fill, check, hover, text
Options: --name <name> (filter role by accessible name), --exact (exact, case-sensitive match; for role it applies to the accessible name, whose default is a case-insensitive substring)
Examples:
agent-browser find role button click --name "Submit"
agent-browser find role heading text --name "Skills" # implicit roles work: <h2>=heading, <ul>=list, top-level <header>=banner
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "test@test.com"
agent-browser find first ".item" click
agent-browser find nth 2 "a" textWait
agent-browser wait <selector> # Wait for element to be visible
agent-browser wait <ms> # Wait for time (milliseconds)
agent-browser wait --text "Welcome" # Wait for text to appear (substring match)
agent-browser wait --url "**/dash" # Wait for URL pattern
agent-browser wait --load networkidle # Wait for load state
agent-browser wait --fn "window.ready === true" # Wait for JS condition
# Wait for text/element to disappear
agent-browser wait --fn "!document.body.innerText.includes('Loading...')"
agent-browser wait "#spinner" --state hiddenLoad states: load, domcontentloaded, networkidle
Batch Execution
Execute multiple commands in a single invocation. Commands can be passed as quoted arguments or piped as JSON via stdin. This avoids per-command process startup overhead when running multi-step workflows.
# Argument mode: each quoted argument is a full command
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
# With --bail to stop on first error
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"
# Stdin mode: pipe commands as JSON
echo '[
["open", "https://example.com"],
["snapshot", "-i"],
["click", "@e1"],
["screenshot", "result.png"]
]' | agent-browser batch --jsonClipboard
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)Mouse Control
agent-browser mouse move <x> <y> # Move mouse
agent-browser mouse down [button] # Press button (left/right/middle)
agent-browser mouse up [button] # Release button
agent-browser mouse wheel <dy> [dx] # Scroll wheelBrowser 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 schemeCookies & Storage
agent-browser cookies # Get all cookies
agent-browser cookies set <name> <val> # Set cookie
agent-browser cookies set --curl <file> # Import cookies from a Copy-as-cURL dump,
# JSON array, or bare Cookie header (auto-detected)
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 sessionStorageNetwork
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 route '*' --abort --resource-type script # Block scripts only
agent-browser network unroute [url] # Remove routes
agent-browser network requests # View tracked requests
agent-browser network requests --filter api # Filter requests
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 (embeds text response bodies)
agent-browser network har start --content all # Embed all response bodies (binary as base64)
agent-browser network har start --content none # Metadata only, no bodies
agent-browser network har stop [output.har] # Stop and save HAR (temp path if omitted)Tabs & Windows
agent-browser tab # List tabs (shows `tabId` and optional label)
agent-browser tab new [url] # New tab (optionally with URL)
agent-browser tab new --label docs [url] # New tab with a user-assigned label
agent-browser tab <t<N>|label> # Switch to a tab by id or label
agent-browser tab close [t<N>|label] # Close a tab (defaults to active)
agent-browser window new # New windowTab ids are stable strings of the form t1, t2, t3. They're never reused within a session, so scripts and agents can keep referring to the same tab even after other tabs are opened or closed. Positional integers like tab 2 are not accepted; the t prefix disambiguates handles from indices and mirrors the @e1 convention used for element refs.
You can also assign a memorable label (docs, app, admin) and use it interchangeably with the id. Labels are never auto-generated and never rewritten on navigation — they're yours to name and keep:
agent-browser tab new --label docs https://docs.example.com
agent-browser tab docs # switch to the docs tab
agent-browser snapshot # populate refs for docs
agent-browser click @e3 # click uses docs's refs
agent-browser tab close docs # close by labelSwitching to a tab discarded by Chrome's Memory Saver reactivates it, since a discarded tab has no renderer to drive. Reactivation reloads the discarded page and resets its unsaved state, and the switch result reports "revived": true. A tab whose page is paused by a JavaScript dialog is alive rather than discarded, so the switch leaves it untouched and reports "dialogBlocked": true; resolve the dialog with dialog accept or dialog dismiss before interacting. Closing the active tab onto a discarded successor revives it the same way and reports "activeTabRevived": true.
Frames
agent-browser frame <sel> # Switch to iframe
agent-browser frame main # Back to main frameDialogs
agent-browser dialog accept [text] # Accept (with optional prompt text)
agent-browser dialog dismiss # Dismiss
agent-browser dialog status # Check if a dialog is currently openBy 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 is pending, all command responses include a warning field with the dialog type and message.
Diff
agent-browser diff snapshot # Compare current vs last snapshot
agent-browser diff snapshot --baseline before.txt # Compare current vs saved snapshot file
agent-browser diff snapshot --selector "#main" --compact # Scoped snapshot diff
agent-browser diff screenshot --baseline before.png # Visual pixel diff against baseline
agent-browser diff screenshot --baseline b.png -o d.png # Save diff image to custom path
agent-browser diff screenshot --baseline b.png -t 0.2 # Adjust color threshold (0-1)
agent-browser diff url https://v1.com https://v2.com # Compare two URLs (snapshot diff)
agent-browser diff url https://v1.com https://v2.com --screenshot # Also visual diff
agent-browser diff url https://v1.com https://v2.com --wait-until networkidle # Custom wait strategy
agent-browser diff url https://v1.com https://v2.com --selector "#main" # Scope to elementDebug
agent-browser trace start # Start recording 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 console # View console messages (log, error, warn, info)
agent-browser console --json # JSON output with raw CDP args for programmatic access
agent-browser console --clear # Clear console
agent-browser errors # View page errors (uncaught JavaScript exceptions)
agent-browser errors --clear # Clear errors
agent-browser highlight <sel> # Highlight element
agent-browser inspect # Open Chrome DevTools for the active page
agent-browser state save <path> # Save auth state
agent-browser state load <path> # Load auth state
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
agent-browser state clear --all # Clear all saved states
agent-browser state clean --older-than <days> # Delete old statesNavigation
agent-browser back # Go back
agent-browser forward # Go forward
agent-browser reload # Reload page
agent-browser pushstate <url> # SPA client-side nav; auto-detects window.next.router.push,
# falls back to history.pushState + popstatePre-navigation setup
Some flows (SSR debug, auth cookies for protected origins, init scripts) need state set up before the first navigation. Use open with no URL to launch the browser, then stage cookies / routes / init scripts, then navigate. batch sends it all in one CLI call:
agent-browser batch \
'["open"]' \
'["network","route","*","--abort","--resource-type","script"]' \
'["cookies","set","--curl","cookies.curl","--domain","localhost"]' \
'["navigate","http://localhost:3000/target"]'Without batch the same sequence is three commands that all reuse the same daemon (fast, but not one turn).
React / Web Vitals
Agent-browser ships with first-class React introspection and universal Web Vitals metrics. The React commands need the React DevTools hook installed at launch; Web Vitals and pushstate are framework-agnostic.
agent-browser open --enable react-devtools <url> # Launch with React hook installed
agent-browser react tree # Full component tree
agent-browser react inspect <fiberId> # props, hooks, state, source
agent-browser react renders start # Begin fiber render recording
agent-browser react renders stop [--json] # Stop and print profile (--json for raw data)
agent-browser react suspense [--only-dynamic] [--json] # Suspense boundaries + classifier
# --only-dynamic hides the "static" list
agent-browser vitals [url] [--json] # LCP/CLS/TTFB/FCP/INP + hydration summaryEach react ... subcommand requires --enable react-devtools to have been passed at launch (the React DevTools installHook.js is embedded in the binary). Without it the commands error with `React DevTools hook not installed
- relaunch with --enable react-devtools`.
Works on any React app — Next.js, Remix, Vite+React, CRA, TanStack Start, React Native Web, etc. vitals and pushstate are framework-agnostic. vitals prints a summary by default; pass --json for the full structured payload.
Accessibility audits
Run an axe-core accessibility audit against the current page or a URL. The axe-core engine is embedded in the binary, so it works offline and under strict CSP. It runs private partial audits across the page's frame tree and merges serialized results without page messaging, so page-provided window.axe values remain intact and iframe violations retain their frame selector paths. Accessibility audits require a CDP browser and are not available with Safari or iOS WebDriver sessions.
agent-browser a11y # Audit the current page
agent-browser a11y https://example.com # Navigate, then audit
agent-browser a11y --tags wcag2a,wcag2aa # Only rules with these axe tags
agent-browser a11y --selector "#main" # Scope the audit to a subtree
agent-browser a11y example.com --json # Full structured resultsThe default output lists each violation with its impact, rule id, fix guidance URL, and the CSS selectors of failing nodes:
url: https://example.com/
axe-core: 4.12.1 violations: 2 incomplete: 0 passes: 24
[critical] image-alt: Images must have alternative text (3 nodes)
https://dequeuniversity.com/rules/axe/4.12/image-alt
- img.hero
- #logo > img
- footer img
[serious] color-contrast: Elements must meet minimum color contrast ratio thresholds (1 node)
https://dequeuniversity.com/rules/axe/4.12/color-contrast
- .nav a.muted
--json returns the same data structured for automation (counts, violations, incomplete, each violation's nodes with target, html, and failureSummary). Each target preserves axe's selector path arrays, including nested arrays for shadow DOM boundaries. Rules that axe could not evaluate automatically are reported under incomplete for manual review.
Init scripts
agent-browser open --init-script <path> # Register page init script before first navigation
# (repeatable; also AGENT_BROWSER_INIT_SCRIPTS env)
agent-browser addinitscript <js> # Register at runtime (returns identifier)
agent-browser removeinitscript <identifier> # Remove a previously registered init scriptSetup
agent-browser install # Download Chrome from Chrome for Testing (Google's official automation channel)
agent-browser install --with-deps # Also install system deps (Linux)
agent-browser upgrade # Upgrade agent-browser to the latest version
agent-browser doctor # Diagnose the install and auto-clean stale daemon files
agent-browser doctor --fix # Also run destructive repairs (reinstall Chrome, purge old state, ...)
agent-browser doctor --offline --quick # Skip network probes and the live launch test
agent-browser mcp # Start an MCP stdio serverdoctor checks your environment, Chrome install, daemon state, config files, encryption key, providers, network reachability, and runs a live headless browser launch test. Stale socket/pid sidecar files are auto-cleaned. Output is also available as --json for agents.
Skills
agent-browser skills # List available skills
agent-browser skills list # Same as above
agent-browser skills get <name> # Output a skill's full content
agent-browser skills get <name> --full # Include references and templates
agent-browser skills get --all # Output every skill
agent-browser skills path [name] # Print skill directory pathServes 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.
MCP Server
agent-browser mcp
agent-browser mcp --tools all
agent-browser mcp --tools core,network,reactStarts a Model Context Protocol server over stdio. MCP clients launch this command as a subprocess and exchange newline-delimited JSON-RPC on stdin and stdout. The server defaults to MCP protocol 2025-11-25 and accepts older supported client protocol versions during initialization.
The default tools profile is core, which keeps MCP context small for everyday browser automation. Use --tools all for the full typed CLI parity surface, or combine profiles with commas, such as --tools core,network,react.
Profiles:
core— Default. Navigation, snapshots, interaction, waits, reads, screenshots, JavaScript eval, close, tab basics, and profile discoverynetwork— Network routes, request inspection, HAR, headers, credentials, offlinestate— Cookies, storage, auth, saved state, sessions, profiles, skillsdebug— Console/errors, tracing, profiling, recording, a11y audit, clipboard, plugins, doctor, dashboard, install, upgrade, chat, diff, batch, confirm/denytabs— Back/forward/reload, tabs, windows, frames, dialogsreact— React tree/inspect/renders/suspense, vitals, pushstatemobile— Viewport/device/geolocation/media, touch, swipe, mouse, keyboardall— Every MCP tool, including the full typed CLI parity surface
Common tools include:
agent_browser_tools_profilesagent_browser_openagent_browser_snapshotagent_browser_clickagent_browser_fillagent_browser_typeagent_browser_pressagent_browser_wait_for_selectoragent_browser_screenshotagent_browser_get_urlagent_browser_evalagent_browser_close
Each tool has typed fields such as url, selector, text, key, session, and allowedDomains, so MCP clients show meaningful approval prompts instead of raw command arrays. The common allowedDomains array maps to --allowed-domains and activates the same WebRTC containment and launch-mode restrictions. Each tool also accepts extraArgs for advanced CLI flags and exact CLI parity. Tool discovery is paginated and includes read-only/open-world annotations so modern MCP clients can load the large typed surface incrementally.
Example MCP client config:
{
"mcpServers": {
"agent-browser": {
"command": "agent-browser",
"args": ["mcp"]
}
}
}Full parity MCP client config:
{
"mcpServers": {
"agent-browser": {
"command": "agent-browser",
"args": ["mcp", "--tools", "all"]
}
}
}Tool invocations use the same config files and environment variables as the CLI. Use session in the tool arguments, or set AGENT_BROWSER_SESSION, to isolate browser state.
Authentication
agent-browser provides multiple ways to persist login sessions so you don't re-authenticate every run.
Quick summary
| 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 |
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:
# 1. Launch Chrome with remote debugging enabled
# macOS:
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
# Or use --auto-connect to discover an already-running Chrome
# 2. Connect and save the authenticated state
agent-browser --auto-connect state save ./my-auth.json
# 3. Use the saved auth in future sessions
agent-browser --state ./my-auth.json open https://app.example.com/dashboard
# 4. Or use --restore for automatic persistence
SESSION="$(agent-browser session id --scope worktree --prefix myapp)"
agent-browser --session "$SESSION" --restore --state ./my-auth.json open https://app.example.com/dashboard
# From now on, --session "$SESSION" --restore auto-saves/restores this stateSecurity notes:
--remote-debugging-portexposes full browser control on localhost. Any local process can connect. Only use on trusted machines and close Chrome when done.- State files contain session tokens in plaintext. Add them to
.gitignoreand delete when no longer needed. For encryption at rest, setAGENT_BROWSER_ENCRYPTION_KEY(see State Encryption).
For full details on login flows, OAuth, 2FA, cookie-based auth, and the auth vault, see the Authentication docs.
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
# Generate a stable worktree-scoped session id
agent-browser session id --scope worktree --prefix next-dev-loop
# Inspect daemon, launch, and restore status
agent-browser session info --jsonEach session has its own:
- Browser instance
- Cookies and storage
- Navigation history
- Authentication state
Chrome Profile Reuse
The fastest way to use your existing login state: pass a Chrome profile name to --profile:
# List available Chrome profiles
agent-browser profiles
# Reuse your default Chrome profile's login state
agent-browser --profile Default open https://gmail.com
# Use a named profile (by display name or directory name)
agent-browser --profile "Work" open https://app.example.com
# Or via environment variable
AGENT_BROWSER_PROFILE=Default agent-browser open https://gmail.comThis 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.
Note: On Windows, close Chrome before using
--profile <name>if Chrome is running, as some profile files may be locked.
Persistent Profiles
For a persistent custom profile directory that stores state across browser restarts, pass a path to --profile:
# 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.comThe profile directory stores:
- Cookies and localStorage
- IndexedDB data
- Service workers
- Browser cache
- Login sessions
Tip: Use different profile paths for different projects to keep their browser state isolated.
