> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel-labs/agent-browser/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Install Agent Browser">
    Install globally for best performance:

    <CodeGroup>
      ```bash npm theme={null}
      npm install -g agent-browser
      ```

      ```bash pnpm theme={null}
      pnpm add -g agent-browser
      ```

      ```bash yarn theme={null}
      yarn global add agent-browser
      ```
    </CodeGroup>
  </Step>

  <Step title="Download Chromium">
    Agent Browser needs Chromium to run:

    ```bash theme={null}
    agent-browser install
    ```

    On Linux, you may need system dependencies:

    ```bash theme={null}
    agent-browser install --with-deps
    ```
  </Step>

  <Step title="Verify Installation">
    Test that everything works:

    ```bash theme={null}
    agent-browser open example.com
    agent-browser close
    ```

    You should see the browser launch and navigate to example.com.
  </Step>
</Steps>

## Your First Automation

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

<Steps>
  <Step title="Navigate to a Page">
    Open a page with a form:

    ```bash theme={null}
    agent-browser open https://example.com/login
    ```

    The browser will launch (headless by default) and navigate to the URL.
  </Step>

  <Step title="Take a Snapshot">
    Get the accessibility tree with element refs:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Fill the Form">
    Use refs to fill inputs and click buttons:

    ```bash theme={null}
    agent-browser fill @e1 "user@example.com"
    agent-browser fill @e2 "password123"
    agent-browser click @e3
    ```

    Refs are deterministic - `@e1` always refers to the same element from the snapshot.
  </Step>

  <Step title="Get Results">
    Wait for navigation and check the result:

    ```bash theme={null}
    agent-browser wait --load networkidle
    agent-browser get url
    agent-browser snapshot -i
    ```

    This shows the current URL and the new page structure.
  </Step>

  <Step title="Clean Up">
    Close the browser when done:

    ```bash theme={null}
    agent-browser close
    ```
  </Step>
</Steps>

## Alternative Selector Methods

You can also use traditional selectors alongside refs:

<CodeGroup>
  ```bash CSS Selectors theme={null}
  agent-browser click "#submit-button"
  agent-browser fill "#email" "test@example.com"
  agent-browser hover ".dropdown-menu"
  ```

  ```bash Text Selectors theme={null}
  agent-browser click "text=Sign In"
  agent-browser click "text=Submit"
  ```

  ```bash Semantic Locators theme={null}
  agent-browser find role button click --name "Submit"
  agent-browser find label "Email" fill "test@example.com"
  agent-browser find placeholder "Search..." fill "query"
  ```
</CodeGroup>

<Note>
  **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.
</Note>

## Command Chaining

Chain multiple commands for efficiency:

```bash theme={null}
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:

```bash theme={null}
agent-browser snapshot -i --json
```

Returns structured JSON with the accessibility tree and refs:

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```bash theme={null}
agent-browser --headed open example.com
```

The browser window will be visible instead of headless.

## Common Patterns

### Wait for Elements

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
agent-browser back                      # Go back
agent-browser forward                   # Go forward
agent-browser reload                    # Reload page
```

### Screenshots

```bash theme={null}
agent-browser screenshot page.png       # Screenshot
agent-browser screenshot --full full.png # Full page
```

## Annotated Screenshots

For multimodal AI models that can see images:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="brain" href="/concepts/architecture">
    Learn about the Rust CLI + Node.js daemon architecture
  </Card>

  <Card title="All Commands" icon="terminal" href="/cli/all-commands">
    Browse the complete command reference
  </Card>

  <Card title="Security Features" icon="shield" href="/security/overview">
    Auth vault, domain allowlist, action policies
  </Card>

  <Card title="AI Agent Integration" icon="robot" href="/integrations/ai-agents">
    Use with Claude Code, Cursor, and other AI assistants
  </Card>
</CardGroup>