Skip to main content
The actionbook browser command lets AI agents automate any Chromium-based browser. Two modes are available depending on the use case:

​
Modes

ModeFlagHow It WorksBest For
Isolated(default)Launches a new Chrome with a fresh, dedicated profileAutomated tasks, CI/CD, headless, no user data needed
Extension--extensionConnects to the user’s running Chrome via extension bridgeTasks requiring existing login sessions, cookies, personal context
Both modes are designed for AI agents. Isolated gives agents a clean, reproducible environment. Extension lets agents operate inside the user’s real browser — ideal when the task requires existing authentication (e.g., “book my flight”, “reply to that email”).

​
Isolated Mode

Works out of the box — no setup required. The CLI launches a temporary Chrome process with a dedicated profile and connects via CDP. 
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: 
actionbook browser close

​
Extension Mode

Extension mode requires a one-time setup to connect the CLI to your running Chrome.
1

Install the extension

actionbook extension install
This downloads the latest release from GitHub and installs it to ~/.config/actionbook/extension/.
Manual download: If the CLI install fails (e.g., GitHub rate limit), download the .zip from GitHub Releases, unzip it, and load it manually.
2

Load into Chrome

  1. Open chrome://extensions in Chrome
  2. Enable Developer mode (top-right toggle)
  3. Click Load unpacked
  4. Select the directory printed by:
actionbook extension path
3

Start the bridge server

The bridge is the WebSocket relay between CLI and Chrome:
actionbook extension serve
serve runs in the foreground. Stop it with Ctrl+C, or use actionbook extension stop from another terminal.
4

Pair the extension

Native Messaging usually handles pairing automatically. If not:
  1. Click the Actionbook extension icon in Chrome toolbar
  2. Copy the token (abk_...) from the serve terminal output
  3. Paste it into the popup and click Save
5

Verify the connection

actionbook extension status
actionbook extension ping
You should see running and a latency measurement confirming the link is active.
Once paired, add --extension to any browser command, or set the environment variable: 
export ACTIONBOOK_EXTENSION=1

​
Browser Commands

All commands below work in both modes. Add --extension to route through the extension bridge. 
actionbook browser open "https://example.com"
actionbook browser goto "https://example.com/login"
actionbook browser back
actionbook browser forward
actionbook browser reload

​
Page Interaction

actionbook browser click "button[type='submit']"
actionbook browser fill "#username" "demo"
actionbook browser select "#country" "US"
actionbook browser hover ".menu-item"
actionbook browser focus "#search-input"
actionbook browser press "Enter"
actionbook browser wait "#username" --timeout 10000

​
Debug & Export

actionbook browser screenshot output.png --full-page
actionbook browser eval "document.title"
actionbook browser snapshot
actionbook browser html
actionbook browser text

actionbook browser cookies list
actionbook browser cookies get session_id
actionbook browser cookies set demo_cookie hello
actionbook browser cookies delete demo_cookie
actionbook browser cookies clear --domain example.com --yes

​
Tab Management

actionbook browser pages
actionbook browser switch tab:123456
Combine action manuals with browser automation for the best results: 
# 1. Find the action manual
actionbook search "github search repos"

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

# 3. Execute (add --extension to use your own browser)
actionbook browser open "https://github.com"
actionbook browser fill "#query-builder-test" "actionbook"
actionbook browser click "button[type='submit']"

​
Shutdown

​
Isolated Mode

actionbook browser close

​
Extension Mode

Follow this cleanup order: 
# 1. Release the debug connection (detaches from Chrome)
actionbook --extension browser close

# 2. Stop the bridge server
actionbook extension stop

# 3. (Optional) Verify
actionbook extension status    # should show "not running"
Always release the debug connection before stopping the bridge. Skipping step 1 may leave Chrome showing an “Actionbook is debugging this browser” banner.

​
Extension Security

Extension mode includes multiple security layers to protect your browser.

​
Risk Levels

LevelDescriptionExample Operations
L1Read-only, safeeval, snapshot, screenshot
L2Page interactionclick, fill, select, navigation
L3Sensitive operationsCookie writes on banking/payment sites
L3 operations on sensitive domains trigger a confirmation popup in the extension — you must approve them manually.

​
Token Authentication

  • Sessions are authenticated with a token (abk_ prefix)
  • Tokens expire after 30 minutes of idle time
  • The bridge auto-rotates tokens; restart serve if pairing is lost
  • Token comparison uses constant-time algorithms to prevent timing attacks

​
Network Isolation

  • The bridge server only listens on 127.0.0.1 (loopback)
  • No external network access is possible
  • Origin validation enforces exact host matching

​
Troubleshooting

  • Ensure actionbook extension serve is running
  • Confirm the extension is loaded and enabled in chrome://extensions
  • Check that no other process is using port 19222
  • To restart: actionbook extension stop then actionbook extension serve
  • Open the extension popup and paste the latest token from the serve output
  • Tokens expire after 30 minutes of inactivity — restart the bridge
  • Make sure Chrome has at least one visible, active tab
  • Run actionbook --extension browser open <url> first to attach a tab
  • Avoid chrome:// pages — the debugger cannot attach to them
  • Sensitive operations (e.g., cookie writes on banking domains) require manual approval
  • Check the extension popup for a pending confirmation dialog
  • The extension defaults to ws://localhost:19222
  • Start the bridge with: actionbook extension serve --port <PORT>
  • Pass to browser commands: --extension-port <PORT>
  • Anonymous GitHub API allows 60 requests/hour
  • Wait and retry, or download the .zip manually from GitHub Releases
  • Download actionbook-extension-v*.zip from another machine
  • Unzip to ~/.config/actionbook/extension/
  • Run actionbook extension install --force to register native messaging