# Installation

## Global installation (recommended)

Installs the native Rust binary for maximum performance:

```bash
npm install -g agent-browser
agent-browser install  # Download Chrome from Chrome for Testing (first time)
```

This is the fastest option -- commands run through the native Rust CLI directly with sub-millisecond parsing overhead.

## Quick start (no install)

```bash
npx agent-browser install   # Download Chrome (first time only)
npx agent-browser open example.com
```

## Project installation (local dependency)

For projects that want to pin the version in `package.json`:

```bash
npm install agent-browser
npx agent-browser install  # Download Chrome (first time)
```

Then use via `npx` or `package.json` scripts.

## Homebrew (macOS)

```bash
brew install agent-browser
agent-browser install  # Download Chrome (first time)
```

## Cargo (Rust)

```bash
cargo install agent-browser
agent-browser install  # Download Chrome (first time)
```

Compiles from source (~2-3 min). Requires the Rust toolchain ([rustup.rs](https://rustup.rs)).

## From source

```bash
git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build
pnpm build:native
./bin/agent-browser install
pnpm link --global
```

## Linux dependencies

On Linux, install system dependencies:

```bash
agent-browser install --with-deps
```

## Updating

Upgrade to the latest version:

```bash
agent-browser upgrade
```

Detects your installation method (npm, Homebrew, or Cargo) and runs the appropriate update command automatically. Displays the version change on success, or informs you if you are already on the latest version.

## Custom browser

Use a custom browser executable instead of bundled Chromium:

- **Serverless** - Use `@sparticuz/chromium` (~50MB vs ~684MB)
- **System browser** - Use existing Chrome installation
- **Custom builds** - Use modified browser builds

```bash
# Via flag
agent-browser --executable-path /path/to/chromium open example.com

# Via environment variable
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com
```

### Serverless example

Use `@sparticuz/chromium` or similar to obtain a Chromium executable path, then pass it via `--executable-path` or `AGENT_BROWSER_EXECUTABLE_PATH`.

## AI agent setup

agent-browser works with any AI agent out of the box. For richer context:

### AI coding assistants (recommended)

Install the skill for your AI coding assistant:

```bash
npx skills add vercel-labs/agent-browser
```

This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf. The skill is fetched from the repository and stays up to date automatically.

> **Do not** copy `SKILL.md` from `node_modules` -- it will become stale as new features are added. Always use `npx skills add` or reference the repository version.

### AGENTS.md / CLAUDE.md

Add to your instructions file:

```markdown
## Browser Automation

Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.

Core workflow:
1. `agent-browser open <url>` - Navigate to page
2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
4. Re-snapshot after page changes
```
