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”).
-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
For raw CDP connections without a managed provider, use --mode cloud --cdp-endpoint wss://... instead of -p.
The actionbook extension commands manage the Chrome extension and its connection to the actionbook daemon.The recommended install method is the Chrome Web Store (current version: 0.4.0). actionbook extension install is a local fallback — after running it, you must manually load the unpacked extension in Chrome via chrome://extensions > Developer mode > Load unpacked, using the path from actionbook extension path.
actionbook extension status # Bridge status + extension connection stateactionbook extension ping # Measure bridge RTTactionbook extension install # Fallback: install to ~/Actionbook/extension/ (requires manual Chrome load)actionbook extension install --force # Force reinstallactionbook extension uninstall # Remove extension from diskactionbook extension path # Print install path, status, and version
The extension bridge runs inside the actionbook daemon (auto-started by browser commands). extension status shows whether the bridge is listening and the extension is connected. extension ping tests connectivity by connecting to the bridge WebSocket at ws://127.0.0.1:19222.
Extension 0.4.0: Tabs opened by Actionbook are automatically grouped into a Chrome “Actionbook” tab group (toggleable via extension popup). list-tabs in extension mode now returns only Actionbook-managed tabs — other user tabs are hidden. Extensions below 0.4.0 are rejected at handshake.
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.
actionbook browser start --session s1 --open-url https://google.comactionbook browser start --session s1 --max-tracked-requests 1000 # custom network buffer sizeactionbook browser list-sessions # list all active sessions (includes max_tracked_requests)actionbook browser status --session s1 # show session infoactionbook browser restart --session s1 # restart, preserving session_id and max_tracked_requestsactionbook browser close --session s1 # close a session
Both --session and --set-session-id are get-or-create: they reuse a Running session with the given ID, or create one if not found.
When reusing a session, if --profile is passed and does not match the session’s bound profile, the command fails with SESSION_PROFILE_MISMATCH. Omit --profile or pass the matching value to reuse.
actionbook browser list-tabs --session s1 # list all tabsactionbook 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
For running parallel tasks across multiple tabs, use Multi-Session with the --session flag instead of manual tab switching.
wait network-idle is edge-triggered: it only tracks fetch/XHR requests started after the command begins. Pre-existing background connections (SSE, WebSocket, analytics pings) are ignored and do not block. This is an agent-friendly settle signal, not a guarantee of global network silence.
har start accepts --max-entries N to set the ring-buffer cap (default: 10000).
When har stop detects dropped entries, the envelope includes meta.truncated = true and a HAR_TRUNCATED warning in meta.warnings with the drop count and configured cap. Read data.dropped and data.max_entries to decide whether to raise --max-entries or stop recording sooner.
Available since v0.11.0. Requires local mode (default).
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.
# Open three sites in separate sessionsactionbook 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 independentlyactionbook browser snapshot --session research --tab t1 # only sees arxiv.orgactionbook browser snapshot --session social --tab t1 # only sees x.comactionbook browser click "#search" --session shopping --tab t1 # only affects amazon.com
Without --session, commands use a default session.
# List all active sessionsactionbook browser list-sessions# Show session statusactionbook browser status --session research# Close a sessionactionbook browser close --session research
actionbook browser close --session s1 # close a sessionactionbook browser restart --session s1 # restart with same profile/mode
browser close is idempotent — closing an unknown or already-closed session returns ok: true with a warning in meta.warnings, not an error. Safe to call unconditionally during cleanup without checking session existence first. Read meta.warnings to distinguish a fresh close from an already-gone session.
browser eval accepts the expression from three mutually-exclusive sources: a positional argument, --file <path>, or stdin (-).browser eval returns structured error codes on failure. Branch on error.code instead of parsing the message string:Runtime errors (after browser execution):
Code
Meaning
Best practice
EVAL_RUNTIME_ERROR
JS exception
Check expression syntax and referenced variables
EVAL_CROSS_ORIGIN
Cross-origin or CSP block
Use same-origin fetch or proxy server-side
EVAL_RESPONSE_NOT_JSON
Non-JSON response body
Read error.details.content_type and body_head before retrying
EVAL_RESPONSE_NOT_OK
Non-2xx HTTP status
Read error.details.status and body_head to distinguish 403 / challenge / CORS
EVAL_TIMEOUT
Expression exceeded --timeout
Reduce work or increase timeout
CLI-layer errors (before any browser interaction):
Code
Meaning
Best practice
EVAL_ARGS_CONFLICT
Multiple input sources or none
Provide exactly one of: positional, --file, or stdin -
EVAL_FILE_NOT_FOUND
--file path unreadable
Verify the path resolves and is readable
EVAL_STDIN_TTY
- but stdin is a terminal
Pipe the expression: echo 'expr' | actionbook browser eval -
EVAL_STDIN_EMPTY
Stdin produced empty input
Verify the upstream command or pipeline
For EVAL_RESPONSE_NOT_OK and EVAL_RESPONSE_NOT_JSON, inspect error.details.body_head (first ≤256 chars of the response body) to decide whether to retry — a 403 challenge page is not worth retrying blindly.
Browser commands that interact with elements, navigate, or communicate via CDP return structured CDP_* error codes. Branch on error.code:
Code
Meaning
Best practice
Retryable
CDP_NODE_NOT_FOUND
DOM node is stale or nonexistent
Call snapshot to refresh node refs then retry
No
CDP_NOT_INTERACTABLE
Element exists but can’t be acted on
Scroll into view, wait for visibility, or dismiss overlays
No
CDP_NAV_TIMEOUT
Navigation or eval timeout
Increase --timeout or verify URL reachability
Yes
CDP_TARGET_CLOSED
Tab navigated away or session torn down mid-command
Start a fresh session or re-attach to the tab
Yes
CDP_PROTOCOL_ERROR
CDP response malformed (-32xxx codes)
Inspect details.reason and details.cdp_code
No
CDP_GENERIC
Unclassified CDP error (transport/parse)
(no specific remediation)
No
When error.code is a CDP_* code, error.details includes reason (raw CDP message) and cdp_code (upstream numeric code) when available. CDP_NAV_TIMEOUT also includes timeout_ms.
CDP_NAV_TIMEOUT and CDP_TARGET_CLOSED set error.retryable = true in the JSON envelope — orchestrators can auto-retry these. All other CDP codes require caller intervention (e.g. refreshing snapshot refs, scrolling elements into view).
Some interaction paths (cookies, screenshots, PDF, etc.) still emit the legacy CDP_ERROR code. These are being migrated to the structured CDP_* taxonomy (ACT-999).
