agent-browser

0.26.0 verified Sat Apr 25 auth: no javascript

agent-browser is a browser automation CLI optimized for AI agents, built in Rust for speed. The current stable version is 0.26.0, with frequent releases (weekly/biweekly). It differentiates from Puppeteer/Playwright by being a native CLI with zero runtime dependencies (no Node.js required for the daemon), supporting headless Chrome via CDP, AI chat commands, and observability dashboard. It offers both accessibility-ref-based and traditional CSS selector interactions, and includes a daemon for persistent sessions.

Common errors

error agent-browser: command not found ↓

cause The CLI is not installed globally or not in PATH.

fix

Run 'npm install -g agent-browser' and ensure npm global bin directory is in PATH.

error Error: Could not find Chrome. Run 'agent-browser install' to download Chrome. ↓

cause No Chrome installation detected and not yet downloaded via agent-browser.

fix

Run 'agent-browser install' or set the CHROME_PATH environment variable to an existing Chrome/Chromium executable.

error Error: AI_GATEWAY_API_KEY is not set ↓

cause AI chat command requires an API key for the AI Gateway.

fix

Set the AI_GATEWAY_API_KEY environment variable or use --key with the command.

error Error: Failed to connect to daemon. Is the daemon running? ↓

cause agent-browser requires a daemon process to manage browser sessions. It may not be started or has crashed.

fix

Run 'agent-browser daemon' to start the daemon, or use 'agent-browser open' to start automatically.

Warnings

gotcha agent-browser is a CLI tool, not a Node.js library. Do not import it via require/import in JavaScript/TypeScript code. Use child_process.exec or similar to invoke the CLI. ↓

fix Use execSync or spawn from child_process module to run commands.

breaking From v0.25.0, the 'chat' command requires AI_GATEWAY_API_KEY environment variable. Missing it will cause an error. ↓

fix Set AI_GATEWAY_API_KEY or use --key flag with the command.

gotcha The 'install' command downloads Chrome from Chrome for Testing. If you already have Chrome, Brave, etc., it may still download its own executable (~200MB). ↓

fix Use --no-install or configure to use existing browser via CHROME_PATH environment variable.

breaking In v0.24.0, the 'provider' flag was added for cloud browser providers (e.g., AWS Bedrock AgentCore). Using '--provider' without specifying a valid provider may break existing scripts. ↓

fix Ensure scripts using --provider are updated to specify the provider name.

gotcha The daemon process may persist after your session ends. Use 'agent-browser stop' to kill it, otherwise it may occupy the port. ↓

fix Run 'agent-browser stop' or kill the daemon process manually.

breaking In v0.23.4, a fix was applied to prevent daemon hang on Linux due to SIGCHLD race condition. Users on older versions may experience hangs. ↓

fix Upgrade to v0.23.4 or later.

deprecated The 'dashboard install' command is deprecated as of v0.25.1. The dashboard is now embedded in the CLI binary. ↓

fix Simply use 'agent-browser dashboard' without prior install.

Install

npm install agent-browser

yarn add agent-browser

pnpm add agent-browser

Imports

agent-browser (CLI)
wrong
```
const agentBrowser = require('agent-browser')
```
correct
```
npm install -g agent-browser or npx agent-browser
```
agent-browser is a CLI tool, not a library. Use as global command or via npx.
agent-browser (npm package)
wrong
```
npm install @vercel/agent-browser
```
correct
```
npm install agent-browser
```
Package name is 'agent-browser', scoped packages are not correct.
Homebrew install
wrong
```
brew install vercel/agent-browser
```
correct
```
brew install agent-browser
```
Homebrew formula is just 'agent-browser'.

Quickstart

Shows global install, Chrome download, navigating to a URL, taking a snapshot, clicking a ref, filling a form, getting text, taking a screenshot, and closing the browser.

npm install -g agent-browser
agent-browser install
agent-browser open example.com
agent-browser snapshot
agent-browser click @e2
agent-browser fill @e3 "test@example.com"
agent-browser get text @e1
agent-browser screenshot page.png
agent-browser close