vercel-labs/agent-browser gained 132 GitHub stars in a day this week. It is a native Rust command-line tool that gives an AI agent a browser it can drive one shell command at a time. The agent opens a page, asks for a snapshot, and gets back the page as compact text with a short reference for each element, such as @e1. It then clicks or types by reference and reads the page again to check the result.
The idea is simple and it fits how coding agents already work: they are good at shell commands and text, not at pixels. This guide covers how the tool works, how to install it, what the commands look like, and the limits its own documentation states.
TL;DR: agent-browser at a glance #
| Question | Answer, per the README and docs |
|---|---|
| What is it? | A native Rust CLI for browser automation by AI agents |
| Who makes it? | Vercel Labs |
| How does the agent see a page? | snapshot returns an accessibility-tree view with refs like@e1 |
| How does it control the browser? | A background daemon talks to Chrome over the Chrome DevTools Protocol |
| Install? | npm install -g agent-browser , thenagent-browser install |
| Licence? | Apache-2.0 |
| MCP support? | agent-browser mcp starts an MCP server over stdio |
| Safe by default? | No. Navigation, action and output controls are opt-in |
| Platforms? | macOS (ARM64, x64), Linux (ARM64, x64, glibc and musl), Windows x64 |
How does agent-browser work? #
The CLI sends each command to a background daemon. The daemon starts on the first command and controls the browser over the Chrome DevTools Protocol. The browser stays open between commands, so each step is one short shell call. Each --session gets its own daemon and browser. By default, a headless browser closes and the daemon exits after one hour with no commands.
Chrome for Testing is the default browser. The README also lists other options: attach to a running Chrome with --cdp or --auto-connect, pick the Lightpanda or Obscura engine with --engine, drive Mobile Safari in the iOS Simulator, or use a cloud provider such as Browserbase, Browserless, Browser Use, Kernel or AgentCore.
A cursor following a path across blank browser tabs, illustrating agent-browser driving a page one command at a time
Why snapshots and refs matter
A vision-based browser agent takes a screenshot, guesses coordinates and clicks. agent-browser takes a different route. snapshot prints the page as an accessibility tree, and each interactive element gets a ref. For example.com, the README shows a single line: a link named "Learn more" with ref=e1.
That has practical consequences:
- Smaller context. Text snapshots are compact, and the
-iflag limits output to interactive elements. - Stable targets. The agent acts on a named ref instead of a pixel position.
- Loud failures. The README says a click fails instead of reporting success when the target is hidden, disabled, outside the viewport or covered by another element such as a consent banner.
- Short-lived refs. Refs describe the page at the time of the snapshot. After navigation or a DOM change, take a new snapshot before using refs again.
The same ideas appear in Vercel's agent-desktop tool, which applies accessibility trees to desktop apps.
How do I install and run it? #
npm install -g agent-browser
agent-browser install # first time only: downloads Chrome for Testing
Homebrew users can run brew install agent-browser. To try it with no install, run npx agent-browser open example.com. On Linux, agent-browser install --with-deps also installs the browser's system libraries.
A first session, straight from the README:
agent-browser open example.com
agent-browser snapshot -i # interactive elements, each with a ref
agent-browser click @e1 # act on a ref from that snapshot
agent-browser get url # check the result
agent-browser close
CSS selectors, text, XPath and semantic locators also work, for example agent-browser find role button click --name "Submit".
The command groups
The README table groups the commands. Highlights:
| Group | Examples |
|---|---|
| Navigate and read | open ,back ,reload ,read ,snapshot ,get |
| Interact | click ,fill ,type ,press ,hover ,select ,scroll ,drag ,upload ,find |
| Capture | screenshot ,pdf ,record ,download ,diff |
| Page and network state | cookies ,storage ,network ,eval ,clipboard |
| Debug and performance | console ,errors ,trace ,profiler ,vitals ,react ,a11y |
| Sessions and auth | session ,state ,auth ,profiles ,confirm ,deny |
| Agents and integrations | skills ,mcp ,webmcp ,flow ,chat ,batch ,plugin |
| Observe | stream ,dashboard |
The debug group is notable. An agent can read console errors, trace a page, and measure web vitals, which makes the tool useful for testing your own app, not only for scraping.
How do I hook it up to Claude Code, Codex or MCP? #
The CLI ships skills that match its version. The agent runs agent-browser skills get core to load the core loop, refs, waiting and common workflows, and agent-browser skills list shows specialised skills such as electron and slack.
There are three ways to wire it in, per the README:
- Install the discovery skill:
npx skills add vercel-labs/agent-browser. The installed skill is a thin stub that tells the agent to load the CLI's own instructions, so they always match the installed version. - Edit AGENTS.md: add a line telling the agent to use
agent-browserand to runagent-browser skills get corefirst. - Use MCP:
agent-browser mcpstarts an MCP server over stdio for MCP clients.
If agent skills are new to you, start with our guide to agent skills. For a comparable hosted option, see our post on Browserbase skills for Claude Code, and for a lightweight engine you can select with --engine, see the Lightpanda 1.0 guide.
What does the security page actually say? #
This is the part to read before you let an agent loose on the open web. The security documentation states: "Navigation, action, and output controls are opt-in. By default, agent-browser imposes no restrictions on navigation, actions, or output."
The threat model lists the risks the tool tries to mitigate, and the matching controls:
| Threat | Control named in the docs |
|---|---|
| Credential exposure | An auth vault; stored passwords never enter the LLM context, and vault operations run locally |
| Prompt injection via page content | --content-boundaries markers that separate tool output from untrusted page text |
| Navigation to attacker domains and data exfiltration | --allowed-domains , which blocks navigations, sub-resource requests, WebSocket, EventSource and sendBeacon calls to non-allowed domains |
| Destructive actions | --action-policy and--confirm-actions for operations such as eval, downloads and uploads |
| Context flooding | --max-output to cap page-sourced content |
The docs are candid about gaps. Among the known limitations they list:
- WebSocket and EventSource blocking is best-effort, and page scripts could restore constructors if the eval category is allowed. The docs say to deny eval through the action policy for maximum protection.
- The domain allowlist "is not an operating-system firewall". Combine it with host, container or network egress controls if you need a boundary below the browser process.
- The allowlist cannot be used with attach modes, profiles, saved state, iOS, Safari or direct-page provider plugins, because pages might run before containment can be verified.
- Content boundaries are defence-in-depth and depend on the model respecting markers.
- Confirmations auto-deny after 60 seconds, and also when stdin is not a terminal.
- Plugins are local executables and are not sandboxed.
The tool also warns when your Chrome is behind the current stable release and later releases fixed CVEs. You can turn that off with AGENT_BROWSER_NO_VERSION_CHECK=1.
A safer starting configuration
A reasonable first run, based on the documented flags:
agent-browser --allowed-domains example.com --max-output 20000 open example.com
Check the exact flag placement in the documentation for your version. Then add an action policy that denies eval, and run the agent inside a container or a VM with network egress limits. For more on why that matters, read our post on a browser agent autonomy incident and on a VM escape that hit agent sandboxes. To block dangerous agent actions before they run, you can also look at AgentBeam, the agent security platform from the explainx.ai team.
How does it compare with other approaches? #
| Approach | How the agent sees the page | Trade-off |
|---|---|---|
| agent-browser | Accessibility snapshot with refs, via shell | Light on context; relies on pages having a useful accessibility tree |
| Vision computer use | Screenshots and coordinates | Works on any visual UI; heavier and less precise |
| Hosted browser skills | Cloud browser plus helper CLI | Less setup; sessions run on a vendor |
| Edge runtimes | Browser built into the platform | See Cloudflare Kitesurf |
For the vision route, our Claude computer use and browser skills post shows how a model-side approach differs. I have not benchmarked agent-browser against any of these, and the README does not publish accuracy numbers, so treat the comparison as design differences, not performance.
Who should try it, and what should you test? #
If you build coding agents, QA agents or research agents that work from a terminal, agent-browser is a small, scriptable way to give them a browser. Good first tests:
- A login-free read task: open a documentation site, snapshot, and extract a table.
- A form on your own staging site, using
fillandclickwith refs, anddiffto compare before and after. - A debug pass using
console,errorsandvitalsagainst your own app. - A prompt-injection drill: a test page with hidden instructions, run with and without
--content-boundaries.
Measure steps, tokens and failure rates yourself before relying on it. The repository shows 806 commits, so it moves fast; pin a version.
Bottom line #
agent-browser makes browser control a plain shell workflow: snapshot, ref, act, verify. It is Apache-2.0, cross-platform, and documents its limits openly. Its safety controls are off until you switch them on, so a production deployment needs the allowlist, an action policy and a boundary outside the browser.
Star counts, flags and platform support are accurate as of November 5, 2026 and may change in the repository and docs.