agent-browser: Let AI agents drive browsers from the shell
A Rust CLI for AI agents to operate webpages from the shell, using snapshot refs instead of fragile coordinates.
GitHub vercel-labs/agent-browser Updated 2026-11-06 Branch main Stars 45.9K Forks 3.1K
Rust TypeScript Browser automation Chrome for Testing AI agents CLI

🧭 Decision Guide

Try it if you

  • You need an AI agent to operate webpages with open, snapshot, click, and get.
    The README's “Quick start” shows these commands; “For AI agents” describes the agent workflow.
  • Your agent harness needs browser integration through MCP, skills.sh, or AGENTS.md.
    “For AI agents” lists agent-browser mcp, npx skills add, and AGENTS.md configuration.
  • The project needs Chrome DevTools Protocol, Lightpanda, Obscura, or a cloud browser provider.
    “How it works” explicitly lists --cdp, --auto-connect, --engine, and providers including Browserbase and Browserless.

Skip it if you

  • Your automation cannot run snapshot again after navigation or DOM changes.
    “Quick start” says refs describe only the page at snapshot time and require a new snapshot after changes.
  • Target pages are often covered by consent banners and the workflow cannot handle the covering element before retrying click.
    “Quick start” says click fails for covered, hidden, disabled, or off-viewport targets.
  • The runtime is not macOS, Linux, or Windows x64 and you cannot provide a corresponding build method.
    “Platforms” lists macOS ARM64/x64, Linux ARM64/x64 glibc/musl, and Windows x64 only.

Requirements

  • Prebuilt installation uses Node.js/npm; source builds require Node.js 24+, pnpm 11+, and Rust. / 预编译安装需要 Node.js/npm;源码构建需要 Node.js 24 或更高、pnpm 11 或更高以及 Rust。
  • First use requires agent-browser install to download Chrome for Testing; Linux can use agent-browser install --with-deps for system libraries. / 首次使用需要运行 agent-browser install 下载 Chrome for Testing;Linux 可用 agent-browser install --with-deps 安装系统库。
  • The project supports macOS ARM64/x64, Linux ARM64/x64 glibc/musl, and Windows x64. / 项目支持 macOS ARM64/x64、Linux ARM64/x64 glibc/musl 和 Windows x64。

First step (verbatim from README)

agent-browser open example.com

Watch out

  • Do not reuse old refs such as @e1 across navigation, or click may target stale page state.
    The README's “Quick start” explanation of refs and snapshot timing.
  • When a consent banner covers the target, handle the covering element before taking a new snapshot and clicking again.
    The README's “Quick start” explanation of click failure conditions.
  • End-to-end source tests launch real headless Chrome and require --ignored --test-threads=1.
    cargo test e2e -- --ignored --test-threads=1 in “Development”.
  • Each --session uses its own daemon and browser, which close after one hour of inactivity by default.
    The “How it works” explanation of sessions, daemons, and the one-hour timeout.

Alternatives

  • Browserbase:When you need a cloud browser provider rather than local Chrome for Testing, the README lists Browserbase as an available provider.
    README “How it works”
  • Browserless:When you need the Browserless cloud browser service, the README lists it as a connectable cloud browser provider.
    README “How it works”
  • Lightpanda:When you want an engine other than Chrome for Testing, the README supports selecting Lightpanda with --engine.
    README “How it works”

Not stated in the README

  • The material does not provide performance, compatibility, or resource-usage comparisons across browser engines. / 材料没有给出不同浏览器引擎的性能、兼容性或资源占用对比。
  • The material does not specify the Chrome for Testing version, concurrent-session limit, or throughput. / 材料没有说明 Chrome for Testing 的具体版本、并发会话上限或吞吐量。
  • The material does not provide detailed authentication examples or limits for the auth vault and security boundaries. / 材料没有给出认证流程、auth vault 的配置示例及安全边界的详细限制。
  • The material does not describe installation-failure handling or system-dependency differences across Windows, macOS, and Linux. / 材料没有说明 Windows、macOS 和 Linux 各平台的安装失败处理或系统依赖差异。

💡 Deep Analysis

6
Yes I orchestrate an AI agent from Shell and need it to navigate, click, and verify results instead of running one fully prewritten script. Is agent-browser suitable?
For: An automation developer orchestrating an AI agent from Shell to operate real websites step by step

Yes, because it exposes browser control as short commands while preserving browser state between calls.

  • snapshot -i returns a compact accessibility tree and assigns refs such as @e1, so the model does not need to consume the full DOM.
  • A background daemon keeps the browser alive; each session has its own daemon and browser, which supports an observe–act–observe loop.
  • The README explicitly requires a new snapshot after navigation or DOM changes. Click also fails when an element is hidden, disabled, outside the viewport, or covered, instead of falsely reporting success.
  • The Shell interface includes open, snapshot, click, and get, while version-matched skills provide the agent with the current command and waiting guidance.

It is a stronger fit for incremental agent decisions than for replaying a completely fixed script with long-lived selectors.

  • README: agent-browser is a native Rust CLI that gives an AI agent a browser it can drive one command at a time
  • README: snapshot returns the page as compact text with a ref such as @e1
  • README: After navigation or a DOM change, take a new snapshot before using refs again
  • README: How it works; For AI agents
agent-browser open example.com
Not stated in the README:The README does not specify planning accuracy, call count, or end-to-end latency for any particular AI model on complex pages.;It does not specify how an agent should automatically determine that a business action has succeeded.
Yes I connect an AI agent through an MCP client and cannot maintain hand-written command documentation synchronized with the agent-browser CLI. Can this project reduce version drift?
For: An integration engineer connecting an agent through an MCP client and wanting to avoid CLI-version drift in tool instructions

Yes, because the project provides both an MCP entry point and skills derived from the installed CLI version, although it does not replace the engineering needed to interpret results and recover from failures.

  • The README explicitly supports agent-browser mcp, which starts an MCP server over stdio for MCP clients.
  • agent-browser skills get core provides the core loop, refs, waiting rules, and common workflows; --ref commands and --full add command references and templates.
  • The discovery skill is described as a thin stub that tells the agent to load the current CLI’s skills get core, so instructions follow the installed version rather than a permanently copied document.
  • MCP remains only an integration layer: refs still become invalid after navigation or DOM changes, so the agent must re-observe and handle dialogs, waits, and failures.

This is a strong fit when maintaining static tool prompts is undesirable, but the README does not prove that every MCP client handles session lifecycles identically.

  • README: For AI agents; agent-browser mcp starts an MCP server over stdio
  • README: agent-browser skills get core
  • README: The installed skill is a thin stub that tells the agent to load agent-browser skills get core
  • README: After navigation or a DOM change, take a new snapshot before using refs again
agent-browser skills get core
Not stated in the README:The README does not provide an MCP-client compatibility matrix, concurrency behavior, or error-propagation details.;It does not say whether skills are automatically injected into the model context on every command.;It does not specify how daemon and browser state recover after an MCP session disconnects.
It depends I need an AI agent to operate a logged-in enterprise admin site, but access domains and high-risk actions must be restricted. Are agent-browser's security features sufficient by themselves?
For: An engineer responsible for securing a high-privilege enterprise agent and needing domain, action, and authentication-state controls

It depends: the project includes agent-oriented security controls, but the README is not sufficient to prove that it alone meets the full requirements of a high-privilege production environment.

  • The command table includes confirm, deny, auth, profiles, session, and state. The project insights also mention an authentication vault, domain allowlists, and action policies, showing that autonomous-agent risk boundaries are considered.
  • Each session has an independent daemon and browser, which helps isolate pages, tabs, and authentication state between tasks.
  • The project insights explicitly warn that cookies, storage, network, eval, and authentication features may expose highly sensitive browser state; production use requires least privilege, domain limits, auditing, and confirmation.
  • Apache-2.0 describes the software license, not permission to automate a target website, and it does not by itself solve credential custody, audit retention, MFA, privilege escalation, or rollback.

It can be part of a security control layer, but the README does not justify treating it as a complete enterprise agent-security solution.

  • README Commands: Sessions and auth includes session, state, auth, profiles, confirm, deny
  • Project insight key_features: authentication vault, domain allowlists, and action policies
  • Project insight usage_limitations: cookies, storage, network, eval, and authentication features can access highly sensitive browser state
  • Project data: Apache License 2.0
agent-browser --help
Not stated in the README:The README does not describe defaults, configuration formats, or bypass behavior for domain allowlists, action policies, and confirm/deny.;It does not specify whether audit logs contain complete action, authentication-access, and policy-decision records.;It does not explain the concrete interception or human-approval flow for MFA, CAPTCHA, and high-risk actions.
It depends I run Chrome for Testing in Linux CI and need login, tabs, and page state to survive across multiple CLI commands. Is agent-browser suitable, and what deployment constraints matter?
For: An enterprise automation engineer running Chrome for Testing in Linux CI and needing persistent login state for back-office workflows

It depends: the stateful daemon and Linux installation path fit this workflow, but authentication, resource usage, and headless-environment constraints may still block deployment.

  • The daemon starts on the first command and keeps the browser open. Each --session owns an independent daemon and browser, which fits a multi-step back-office flow.
  • Chrome for Testing is the default browser. On Linux, agent-browser install --with-deps installs browser system libraries, and native binaries are available for Linux ARM64, x64, glibc, and musl.
  • session, state, auth, and profiles cover session and authentication persistence, but the daemon closes after one hour without commands unless session persistence is configured.
  • The README lists CDP and cloud-browser options, but does not promise equivalent authentication, concurrency capacity, or network behavior across providers.

It covers the basic deployment model, but credential injection, browser dependencies, and concurrent-session capacity must be verified separately for the CI environment.

  • README: How it works; Each --session gets its own daemon and browser
  • README: By default, the daemon closes a headless browser and exits after one hour without commands
  • README: Linux: agent-browser install --with-deps
  • README: Platforms; Sessions and auth
agent-browser install --with-deps
Not stated in the README:The README gives no session-per-worker limit, memory profile, or startup-time figures for Linux CI.;It does not describe a specific integration with an authentication vault or CI secret manager.;It does not say whether the target back-office system's CAPTCHA, MFA, or anti-automation controls will work.
Yes I maintain a React back office and need screenshots, page diffs, and console, error, and React diagnostics during regression tests. Is agent-browser suitable for replacing part of my existing browser tooling?
For: A test engineer responsible for end-to-end regression of a React back office and needing screenshots, DOM diffs, and diagnostics

Yes, for this regression and debugging workflow, because the command surface covers capture, diffing, and React diagnostics rather than only browser interaction.

  • The command table lists screenshot, pdf, record, download, and diff, allowing visual or page artifacts to be retained for regression checks.
  • The debugging group includes console, errors, trace, profiler, vitals, react, and a11y, which are relevant to diagnosing failures in a React page.
  • highlight, inspect, and snapshot help verify which element the agent or test actually targeted; get and read provide additional page content.
  • However, the primary observation surface is the accessibility tree. The project does not claim that it fully represents Canvas, pixel-level layout, or every Shadow DOM implementation, so a visual test should not rely on snapshots alone.

It is therefore a good layer for end-to-end actions, evidence capture, and diagnosis; pixel-perfect acceptance still requires validating the precise screenshot and diff behavior.

  • README Commands: Capture includes screenshot, pdf, record, download, diff
  • README Commands: Debug and performance includes console, errors, highlight, inspect, trace, profiler, vitals, react, a11y
  • README: agent-browser is a native Rust CLI that reads pages as an accessibility tree
  • Project insight usage_limitations: accessibility snapshots may not fully represent visual layout, Canvas content, or some custom components
agent-browser open example.com
Not stated in the README:The README does not specify whether diff is text-based, DOM-based, screenshot-based, or multi-mode, nor does it define comparison thresholds.;It does not state which React versions are supported by the React diagnostics.;It provides no coverage data for complex Shadow DOM or Canvas pages.
It depends I cannot always download and start local Chrome for Testing: some environments already have a running Chrome, while others require Lightpanda or Browserbase. Can agent-browser preserve one CLI interaction model?
For: An infrastructure engineer who must connect to an already-running Chrome, Lightpanda, or a cloud browser

It depends: the project explicitly supports several browser connection modes, but the README does not guarantee equivalent compatibility, latency, or capabilities across engines and providers.

  • Chrome for Testing is the default, while --cdp and --auto-connect attach to an already-running Chrome, which fits environments that cannot start another browser.
  • The README also lists --engine for Lightpanda or Obscura, iOS Simulator support, and cloud providers including Browserbase, Browserless, Browser Use, Kernel, and AgentCore.
  • These modes share the agent-browser command surface for navigation, snapshots, interaction, sessions, and debugging, keeping the agent-facing interface relatively independent from infrastructure.
  • However, the project insights state that alternative engines, iOS Simulator, and cloud browsers may differ in functionality, compatibility, latency, and debugging. Canvas, nonstandard controls, and anti-automation behavior can also reduce snapshot and interaction reliability.

It is a good candidate for a unified control layer, but default Chrome behavior should not be assumed for every backend.

  • README: How it works; You can also attach to a running Chrome with --cdp or --auto-connect
  • README: select the Lightpanda or Obscura engine with --engine
  • README: use a cloud browser provider such as Browserbase, Browserless, Browser Use, Kernel, or AgentCore
  • Project insight common_pitfalls: cloud browsers, alternative engines, and iOS Simulator may differ in functionality, compatibility, latency, and debugging
npx agent-browser open example.com
Not stated in the README:The README provides no command, version, or feature matrix for the engines and cloud providers.;It gives no latency, cost, or concurrency data comparing CDP, cloud browsers, and local Chrome.;It does not say whether iOS Simulator supports all session, auth, and debugging commands.

✨ Highlights

  • A native Rust CLI drives Chrome for Testing one command at a time
  • snapshot exposes AI-usable page refs such as @e1
  • Supports MCP, skills, WebMCP, and multiple browser engines
  • Native binaries cover macOS, Linux, and Windows x64

🔧 Engineering

  • Build an AI browser loop with open, snapshot, click, and get
  • A background daemon keeps the browser session alive with session persistence
  • Provides debugging commands including cookies, network, trace, profiler, and a11y

⚠️ Risks

  • Old refs become stale after DOM changes or navigation; run snapshot again
  • click fails when targets are hidden, disabled, or covered by a consent banner
  • Linux --with-deps installs browser system libraries and changes the environment
  • The daemon closes the headless browser after one hour without commands by default

👥 For who?

  • Automation teams that need AI agents to operate webpages from the shell
  • Developers integrating with agent harnesses through MCP, AGENTS.md, or skills.sh
  • Projects needing Chrome DevTools Protocol, iOS Simulator, or cloud browsers