Quickstart

Get started with Agent Browser in 5 minutes

Get up and running with Agent Browser quickly. This guide walks you through the core workflow: installing, navigating to a page, taking a snapshot, and interacting with elements using refs.

Prerequisites

• Node.js 18+ installed
• Basic command line knowledge

Install and Setup

1. Install Agent Browser

   Install globally for best performance:

   npm

   npm install -g agent-browser
   
2. Download Chromium

   Agent Browser needs Chromium to run:

   agent-browser install
   

   On Linux, you may need system dependencies:

   agent-browser install --with-deps
   
3. Verify Installation

   Test that everything works:

   agent-browser open example.com
   agent-browser close
   

   You should see the browser launch and navigate to example.com.

Your First Automation

Let’s automate a simple form fill workflow using the snapshot-ref pattern.

1. Navigate to a Page

   Open a page with a form:

   agent-browser open https://example.com/login
   

   The browser will launch (headless by default) and navigate to the URL.

2. Take a Snapshot

   Get the accessibility tree with element refs:

   agent-browser snapshot -i
   

   The -i flag shows only interactive elements (buttons, inputs, links). Output:

   - textbox "Email" [ref=e1]
   - textbox "Password" [ref=e2] [type=password]
   - button "Sign In" [ref=e3]
   - link "Forgot password?" [ref=e4]
   

   Each element gets a unique @e{N} ref that you can use to interact with it.

3. Fill the Form

   Use refs to fill inputs and click buttons:

   agent-browser fill @e1 "[e-mail]"
   agent-browser fill @e2 "password123"
   agent-browser click @e3
   

   Refs are deterministic - @e1 always refers to the same element from the snapshot.

4. Get Results

   Wait for navigation and check the result:

   agent-browser wait --load networkidle
   agent-browser get url
   agent-browser snapshot -i
   

   This shows the current URL and the new page structure.

5. Clean Up

   Close the browser when done:

   agent-browser close
   

Alternative Selector Methods

You can also use traditional selectors alongside refs:

CSS Selectors

agent-browser click "#submit-button"
agent-browser fill "#email" "[e-mail]"
agent-browser hover ".dropdown-menu"

Refs are recommended for AI agents because they’re deterministic and don’t require DOM knowledge. CSS selectors are useful when you know the page structure.

Command Chaining

Chain multiple commands for efficiency:

agent-browser open example.com && \
  agent-browser snapshot -i && \
  agent-browser fill @e1 "value" && \
  agent-browser click @e2

The browser daemon persists between commands, so chaining is fast and safe.

JSON Output for AI Agents

Use --json for machine-readable output:

agent-browser snapshot -i --json

Returns structured JSON with the accessibility tree and refs:

{
  "success": true,
  "data": {
    "snapshot": "- textbox \"Email\" [ref=e1]\n- button \"Submit\" [ref=e2]",
    "refs": {
      "e1": {
        "role": "textbox",
        "name": "Email",
        "selector": "input[type=\"email\"]"
      },
      "e2": {
        "role": "button",
        "name": "Submit"
      }
    }
  }
}

Sessions for Parallel Browsers

Run multiple isolated browser instances:

# Terminal 1 - First agent
agent-browser --session agent1 open site-a.com
agent-browser --session agent1 snapshot -i

# Terminal 2 - Second agent
agent-browser --session agent2 open site-b.com
agent-browser --session agent2 snapshot -i

Each session has its own browser, cookies, and state.

Headed Mode for Debugging

See what the browser is doing:

agent-browser --headed open example.com

The browser window will be visible instead of headless.

Common Patterns

Wait for Elements

agent-browser wait "#content"           # Wait for element
agent-browser wait 2000                 # Wait 2 seconds
agent-browser wait --text "Welcome"     # Wait for text
agent-browser wait --load networkidle   # Wait for network

Get Information

agent-browser get text @e1              # Get element text
agent-browser get value @e2             # Get input value
agent-browser get attr @e3 "href"       # Get attribute
agent-browser get title                 # Get page title
agent-browser get url                   # Get current URL

Navigate

agent-browser back                      # Go back
agent-browser forward                   # Go forward
agent-browser reload                    # Reload page

Screenshots

agent-browser screenshot page.png       # Screenshot
agent-browser screenshot --full full.png # Full page

Annotated Screenshots

For multimodal AI models that can see images:

agent-browser screenshot --annotate

This overlays numbered labels on interactive elements in the screenshot. The labels correspond to refs ([1] = @e1, [2] = @e2), so you can use the same refs after viewing the annotated screenshot.

Next Steps

Core Concepts

Learn about the Rust CLI + Node.js daemon architecture

All Commands

Browse the complete command reference

Security Features

Auth vault, domain allowlist, action policies

AI Agent Integration

Use with Claude Code, Cursor, and other AI assistants