actionbook__actionbook/docs/guides/browser.mdx

---
title: "Browser Automation"
description: "Control browsers with Actionbook CLI: modes, commands, multi-session, and security"
---

The `actionbook browser` command lets AI agents automate any Chromium-based browser. Three modes are available depending on the use case:

<Note>
  Normal usage: run `actionbook setup` once, then use `actionbook browser ...` commands only.
</Note>

## Modes

| Mode | How It Works | Best For |
|------|-------------|----------|
| **Local** *(default)* | Launches a new Chrome with a fresh, dedicated profile | Automated tasks, CI/CD, headless, no user data needed |
| **Cloud** | Connects to a remote browser via a cloud provider | Scalable headless infra, geo-targeting, persistent profiles in the cloud |
| **Extension** | Connects to the user's running Chrome via extension bridge | Tasks requiring existing login sessions, cookies, personal context |

All three modes are designed for AI agents:

- **Local** gives agents a clean, reproducible environment.
- **Cloud** offloads the browser to a remote provider, suited for production workloads, parallel execution at scale, or IP geolocation control.
- **Extension** lets agents operate inside the user's real browser when the task requires existing authentication (e.g., "book my flight", "reply to that email").

## Local Mode

Works out of the box with no setup. The CLI launches a temporary Chrome process with a dedicated profile and connects via CDP.

```bash
# If local is your default mode (or not configured)
actionbook browser open "https://example.com"
actionbook browser click "button[type='submit']"
actionbook browser fill "#search" "actionbook"
actionbook browser screenshot output.png
```

When done, close the browser:

```bash
actionbook browser close
```

## Cloud Providers

Cloud mode lets you run browser sessions on a remote provider instead of launching a local Chrome. Use the `-p` (or `--provider`) flag with `browser start`:

```bash
actionbook browser start -p hyperbrowser --session s1
```

### Supported Providers

| Provider | Flag Value | Required Env Var | Service |
|----------|-----------|-----------------|---------|
| driver.dev | `driver` | `DRIVER_API_KEY` | [driver.dev](https://driver.dev) |
| Hyperbrowser | `hyperbrowser` | `HYPERBROWSER_API_KEY` | [hyperbrowser.ai](https://hyperbrowser.ai) |
| Browser Use | `browseruse` | `BROWSER_USE_API_KEY` | [browser-use.com](https://browser-use.com) |

### Quick Start

<Steps>
  <Step title="Export your provider API key">
    ```bash
    # Pick one provider
    export DRIVER_API_KEY="your-key"
    # or
    export HYPERBROWSER_API_KEY="your-key"
    # or
    export BROWSER_USE_API_KEY="your-key"
    ```
  </Step>

  <Step title="Start a cloud browser session">
    ```bash
    actionbook browser start -p hyperbrowser --session cloud1
    ```

    The CLI creates a remote browser session and returns the `session_id` and `tab_id` for subsequent commands.
  </Step>

  <Step title="Use browser commands as usual">
    ```bash
    actionbook browser open "https://example.com" --session cloud1
    actionbook browser snapshot --session cloud1 --tab t1
    actionbook browser click "#login" --session cloud1 --tab t1
    ```

    All browser commands work the same way. The session runs on the cloud provider transparently.
  </Step>

  <Step title="Close when done">
    ```bash
    actionbook browser close --session cloud1
    ```

    This terminates the remote browser session and releases provider resources.
  </Step>
</Steps>

### How It Works

- `-p <name>` automatically implies `--mode cloud`, so you don't need to set both
- `-p` is mutually exclusive with `--cdp-endpoint` and `--mode local/extension`
- The CLI forwards provider env vars from your current shell to the daemon at start time (the daemon's own env is frozen at spawn)
- `browser restart --session <id>` mints a **fresh remote session** while preserving the same `session_id`, so you can reset state without losing your addressing handle

<Warning>
  For raw CDP connections without a managed provider, use `--mode cloud --cdp-endpoint wss://...` instead of `-p`.
</Warning>

## Extension Mode Setup

<Note>
  Extension mode is under active development. For most use cases, **Local** or **Cloud** mode is recommended.
</Note>

If you've configured `mode = "extension"` in your config file, you only need to perform this one-time setup.

<Steps>
  <Step title="Install from Chrome Web Store (recommended)">
    1. Open [Actionbook on Chrome Web Store](https://chromewebstore.google.com/detail/actionbook/bebchpafpemheedhcdabookaifcijmfo)
    2. Click **Add to Chrome**
    3. Confirm **Add extension**
  </Step>

  <Step title="Verify with any browser command">
    ```bash
    actionbook browser open "https://example.com"
    actionbook browser snapshot
    ```

    The bridge auto-starts in the background and the extension auto-connects within a few seconds.
  </Step>

  <Step title="Fallback: local debug install (only if Web Store install fails)">
    1. Install the fallback package:

    ```bash
    actionbook extension install
    ```

    2. Open `chrome://extensions`
    3. Enable **Developer mode**
    4. Click **Load unpacked**
    5. Select the path from:

    ```bash
    actionbook extension path
    ```
  </Step>
</Steps>


## Configuration

The recommended way to set your preferred browser mode is via `actionbook setup`.
It writes your choice to `~/.actionbook/config.toml`, so you can run browser commands without extra flags.

### Set Default Mode

Create or edit `~/.actionbook/config.toml`:

```toml
[browser]
# Use "local" (default), "cloud", or "extension"
mode = "local"
```

Once configured, all browser commands will automatically use your chosen mode:

```bash
# No flags needed - uses configured mode
actionbook browser open "https://example.com"
actionbook browser click "button[type='submit']"
```

## Browser Commands

Most commands work in all modes. All per-tab commands require `--session` and `--tab` flags to address a specific tab.

### Session Lifecycle

```bash
actionbook browser start --session s1 --open-url https://google.com
actionbook browser list-sessions                     # list all active sessions
actionbook browser status --session s1               # show session info
actionbook browser restart --session s1              # restart, preserving session_id
actionbook browser close --session s1                # close a session
```

### Tab Management

```bash
actionbook browser list-tabs --session s1                          # list all tabs
actionbook browser new-tab "https://example.com" --session s1      # open a new tab (alias: open)
actionbook browser close-tab --session s1 --tab t1                 # close a tab
```

<Tip>
  For running **parallel tasks** across multiple tabs, use [Multi-Session](#multi-session-parallel-tabs) with the `--session` flag instead of manual tab switching.
</Tip>

### Navigation

```bash
actionbook browser goto "https://example.com/login" --session s1 --tab t1
actionbook browser back --session s1 --tab t1
actionbook browser forward --session s1 --tab t1
actionbook browser reload --session s1 --tab t1
```

### Page Interaction

```bash
actionbook browser click "button[type='submit']" --session s1 --tab t1
actionbook browser fill "#username" "demo" --session s1 --tab t1
actionbook browser type "#search" "hello" --session s1 --tab t1     # append text (does not clear)
actionbook browser select "#country" "US" --session s1 --tab t1
actionbook browser hover ".menu-item" --session s1 --tab t1
actionbook browser focus "#search-input" --session s1 --tab t1
actionbook browser press "Enter" --session s1 --tab t1              # single key or combo
actionbook browser press "Control+A" --session s1 --tab t1          # keyboard shortcuts
actionbook browser scroll down 500 --session s1 --tab t1            # scroll by pixels
actionbook browser drag "#src" "#target" --session s1 --tab t1
actionbook browser mouse-move 100,200 --session s1 --tab t1
actionbook browser cursor-position --session s1 --tab t1
```

<Tip>
  Use `@eN` refs from snapshot output directly as selectors (e.g., `actionbook browser click @e5 --session s1 --tab t1`).
</Tip>

### Wait Conditions

```bash
actionbook browser wait element "#username" --session s1 --tab t1 --timeout 10000
actionbook browser wait navigation --session s1 --tab t1
actionbook browser wait network-idle --session s1 --tab t1
actionbook browser wait condition "document.readyState === 'complete'" --session s1 --tab t1
```

### Observation & Export

```bash
actionbook browser snapshot --session s1 --tab t1                   # accessibility tree
actionbook browser snapshot --interactive --session s1 --tab t1     # only interactive elements
actionbook browser screenshot output.png --session s1 --tab t1
actionbook browser screenshot output.png --full --session s1 --tab t1
actionbook browser pdf report.pdf --session s1 --tab t1
actionbook browser eval "document.title" --session s1 --tab t1
actionbook browser html --session s1 --tab t1
actionbook browser text --session s1 --tab t1
actionbook browser title --session s1 --tab t1
actionbook browser url --session s1 --tab t1
actionbook browser viewport --session s1 --tab t1
actionbook browser inspect-point 100,200 --session s1 --tab t1     # inspect element at coordinates
actionbook browser describe "#submit" --session s1 --tab t1        # element properties & context
actionbook browser box "#submit" --session s1 --tab t1             # element bounding box
actionbook browser attrs "#submit" --session s1 --tab t1           # all element attributes
actionbook browser state "#submit" --session s1 --tab t1           # element state
actionbook browser logs console --session s1 --tab t1              # console logs
actionbook browser logs errors --session s1 --tab t1               # error logs
actionbook browser network requests --session s1 --tab t1          # tracked network requests
```

### Cookie & Storage Operations

```bash
# Cookies (session-level, no --tab needed)
actionbook browser cookies list --session s1
actionbook browser cookies get session_id --session s1
actionbook browser cookies set demo_cookie hello --session s1
actionbook browser cookies delete demo_cookie --session s1
actionbook browser cookies clear --domain example.com --session s1

# Local Storage (window.localStorage)
actionbook browser local-storage list --session s1 --tab t1
actionbook browser local-storage get myKey --session s1 --tab t1
actionbook browser local-storage set myKey "myValue" --session s1 --tab t1
actionbook browser local-storage delete myKey --session s1 --tab t1
actionbook browser local-storage clear myKey --session s1 --tab t1

# Session Storage (window.sessionStorage)
actionbook browser session-storage list --session s1 --tab t1
actionbook browser session-storage get myKey --session s1 --tab t1
actionbook browser session-storage set myKey "myValue" --session s1 --tab t1
actionbook browser session-storage delete myKey --session s1 --tab t1
actionbook browser session-storage clear myKey --session s1 --tab t1
```

### File Upload

```bash
actionbook browser upload "input[type=file]" photo.jpg --session s1 --tab t1
actionbook browser upload "#file-input" a.png b.png --session s1 --tab t1   # multiple files
```

## Multi-Session (Parallel Tabs)

<Note>
  Available since v0.11.0. Requires local mode (default).
</Note>

Multi-session lets you run **multiple independent tabs in a single browser instance**. Each named session is bound to its own tab, so commands sent to one session never affect another.

### Basic Usage

Use the `--session` flag to name a session:

```bash
# Open three sites in separate sessions
actionbook browser start --session research --open-url "https://arxiv.org"
actionbook browser start --session social --open-url "https://x.com"
actionbook browser start --session shopping --open-url "https://amazon.com"

# Each session operates independently
actionbook browser snapshot --session research --tab t1   # only sees arxiv.org
actionbook browser snapshot --session social --tab t1     # only sees x.com
actionbook browser click "#search" --session shopping --tab t1  # only affects amazon.com
```

Without `--session`, commands use a `default` session.

### Session Management

```bash
# List all active sessions
actionbook browser list-sessions

# Show session status
actionbook browser status --session research

# Close a session
actionbook browser close --session research
```

### Common Mistakes

<Warning>
  **Don't create multiple profiles or ports for parallel tabs.** Use `--session` instead.
</Warning>

<AccordionGroup>
  <Accordion title="Creating separate profiles with different ports">
    ```bash
    # WRONG: wasteful, launches 3 Chrome instances
    actionbook browser start --profile work1
    actionbook browser start --profile work2
    actionbook browser start --profile work3
    ```

    ```bash
    # CORRECT: one browser, three sessions
    actionbook browser start --session research --open-url "https://arxiv.org"
    actionbook browser start --session social --open-url "https://x.com"
    actionbook browser start --session shopping --open-url "https://amazon.com"
    ```
  </Accordion>

  <Accordion title="Running snapshot without session distinction">
    ```bash
    # WRONG: all three snapshots see the same (last opened) tab
    actionbook browser snapshot --session default --tab t1
    actionbook browser snapshot --session default --tab t1
    actionbook browser snapshot --session default --tab t1
    ```

    ```bash
    # CORRECT: each snapshot targets a specific session
    actionbook browser snapshot --session research --tab t1
    actionbook browser snapshot --session social --tab t1
    actionbook browser snapshot --session shopping --tab t1
    ```
  </Accordion>
</AccordionGroup>

## Recommended Workflow

Combine action manuals with browser automation for the best results:

```bash
# 1. Find the action manual
actionbook search "github search repos"

# 2. Get verified selectors
actionbook get "<area_id>"

# 3. Execute (uses your configured mode)
actionbook browser open "https://github.com"
actionbook browser fill "#query-builder-test" "actionbook"
actionbook browser click "button[type='submit']"
```

## Shutdown

```bash
actionbook browser close --session s1       # close a session
actionbook browser restart --session s1     # restart with same profile/mode
```


## Extension Security

Extension mode connects via a local WebSocket bridge with the following guarantees:

- The bridge only listens on `127.0.0.1` (loopback), no external network access
- No token or pairing is required; local origin is sufficient for authentication
- The extension identifies itself via a WebSocket handshake with role and version fields
- The bridge validates the connection source (origin + extension ID) before accepting commands

## Troubleshooting

<AccordionGroup>
  <Accordion title="Browser command waits for extension connection">
    - Run any browser command once: `actionbook browser open <url>` (this auto-starts the bridge)
    - Keep Chrome open and confirm the Actionbook extension is enabled in `chrome://extensions`
    - First startup can take a few seconds while the bridge starts and the extension reconnects
  </Accordion>

  <Accordion title="Extension popup shows 'Waiting for bridge' or keeps reconnecting">
    - This usually means the WebSocket handshake did not complete
    - Update CLI: `npm update -g @actionbookdev/cli`
    - Reinstall from [Chrome Web Store](https://chromewebstore.google.com/detail/actionbook/bebchpafpemheedhcdabookaifcijmfo)
    - If needed, use fallback install: `actionbook extension install --force`, then reload it in `chrome://extensions`
    - Click **Connect** in the extension popup to retry
  </Accordion>

  <Accordion title="Commands not using my configured mode">
    - Re-run `actionbook setup` and choose your preferred browser mode
    - Check effective config with `actionbook config show`
    - Environment variables (for example `ACTIONBOOK_BROWSER_MODE`) can override config
  </Accordion>

  <Accordion title="No tab attached">
    - Make sure Chrome has at least one visible, active tab
    - Run `actionbook browser open <url>` first to attach a tab
    - Avoid `chrome://` pages; the debugger cannot attach to them
  </Accordion>

  <Accordion title="Port 19222 in use">
    - Browser mode currently uses a fixed bridge address: `ws://127.0.0.1:19222`
    - Stop the conflicting process on that port (macOS/Linux: `lsof -i :19222`)
    - Then retry your browser command; the bridge will auto-start again
  </Accordion>

  <Accordion title="Chrome Web Store install failed">
    - Retry Web Store install: [Actionbook on Chrome Web Store](https://chromewebstore.google.com/detail/actionbook/bebchpafpemheedhcdabookaifcijmfo)
    - Use local debug fallback: `actionbook extension install`
    - Load it manually from `chrome://extensions` with **Load unpacked**
    - If GitHub API is rate-limited during fallback, wait and retry or download from [GitHub Releases](https://github.com/actionbook/actionbook/releases)
  </Accordion>

</AccordionGroup>