run-agent-browser

Drive agent-browser as a live terminal REPL: one command, read the result, then decide the next. Never chain ad hoc browser work in a script or && unless the user asked for a reusable harness.

Escalate; never dead-end. If a tier fails, diagnose once, then move to the next tier. If every automated tier fails, ask the user for credentials / a CDP URL / a deploy decision — do not stop with "can't."

Authority

agent-browser skills get core
agent-browser COMMAND --help
agent-browser --version

Installed CLI help wins on syntax. This skill owns runtime selection and failure escalation for this host.

Priority ladder (always start at tier 1)

Special cases (skip the ladder only when clearly required):

Stealth is the default (every tier)

Always prefer anti-automation defaults. There is no official agent-browser-plugin-stealth npm package (404); use built-ins + provider stealth flags:

# Local / Steel launch args (tier 1; also apply when launching unmanaged Chrome)
STEALTH_ARGS='--disable-blink-features=AutomationControlled'

# Browserless: stealth ON by default (BROWSERLESS_STEALTH=true)
# Kernel: stealth OFF by default — always set KERNEL_STEALTH=true for this skill
# Proxy (optional, all tiers): --proxy "$AGENT_BROWSER_PROXY" when configured

Never put proxy passwords, API keys, or cookie values in command output, commits, or chat.

Tier 1 — plain local (start here)

No rc file auto-sources a provider env into a fresh zsh shell (the default here) — but .bashrc auto-sources agent-browser-kernel.env (AGENTBROWSERPROVIDER=kernel), and manually source-ing any provider file during tier-3 work leaves that variable exported for the rest of the shell. Always unset it for tier 1 regardless of which shell or prior command ran, or you will silently hit a cloud provider instead of local Chrome.

SESSION="local-$(agent-browser session id --scope cwd --prefix task)"

env -u AGENT_BROWSER_PROVIDER \
  agent-browser --session "$SESSION" \
  --args "--disable-blink-features=AutomationControlled" \
  open https://example.com

env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" snapshot -i
env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" get title
env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" close

Treat as tier-1 failure and escalate when you see: Chrome/Chromium not found, display/Xvfb errors, sandbox/--no-sandbox crashes, CDP bind failures, repeated blank pages with no DOM, or the user is on a machine without a local browser (CI, remote-only laptop).

If the error is specifically Cannot use --cdp and -p/--provider together, you mixed tiers — drop -p/AGENTBROWSERPROVIDER for CDP, or drop --cdp for a provider.

Tier 2 — Steel CDP (self-hosted on this fleet)

Read references/cdp-and-steel.md before changing endpoints or diagnosing attach failures. Short path:

source "$HOME/.config/steel-browser-cdp.env"   # no-op if missing — then ask user / deploy
# If STEEL_AGENT_BROWSER_CDP is empty: ask user for a CDP websocket URL, or offer to deploy Steel
# (deploy path: Coolify compose in crawler-service/deploy/steel-browser/ — use deploy-coolify-cloud skill)

SESSION="steel-$(agent-browser session id --scope cwd --prefix task)"

# Optional clean slate (Steel is single-session / shared page — see reference)
curl -fsS -X POST "$STEEL_API_URL/v1/sessions/release" >/dev/null 2>&1 || true

env -u AGENT_BROWSER_PROVIDER \
  agent-browser --session "$SESSION" --cdp "$STEEL_AGENT_BROWSER_CDP" \
  open https://example.com

env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" --cdp "$STEEL_AGENT_BROWSER_CDP" snapshot -i
env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" --cdp "$STEEL_AGENT_BROWSER_CDP" close
curl -fsS -X POST "$STEEL_API_URL/v1/sessions/release" >/dev/null 2>&1 || true   # full reset; close only detaches

Critical Steel facts (do not skip): one shared Chromium with effectively one page; serialize Steel tasks; --session isolates daemon state only; close detaches, POST …/v1/sessions/release resets. Full semantics, ports, tailnet URLs, and troubleshooting: references/cdp-and-steel.md.

Escalate to tier 3 when: env file missing and user has no CDP URL; health//json/version fail; attach refused after one recovery attempt; or Steel serialization blocks a needed parallel task.

If the user only has a raw CDP link (any host), use tier-2 mechanics with that URL:

env -u AGENT_BROWSER_PROVIDER agent-browser --session cdp-user --cdp "$USER_SUPPLIED_CDP_WS" open https://example.com

Tier 3 — cloud providers (ask, configure, retry)

Read references/providers.md for env files, stealth defaults, and install. Order when the user has not named a provider:

1. Browser Use (-p browseruse) — key often already on this host, but see the known-broken note below before relying on it
2. Kernel (-p kernel) — set KERNEL_STEALTH=true; verified working on this host
3. Browserless (-p browserless) — stealth on by default; verified working on this host
4. Browserbase (-p browserbase) — only if key present / user provides

Known issue (this host, agent-browser 0.33.2, checked 2026-08-03): -p browseruse fails deterministically with ✗ CDP WebSocket connect failed: HTTP error: 400 Bad Request on every attempt — different session names, with/without -v/--debug, fresh shell, doc-verbatim syntax. This is not a bad key: an authenticated API probe returns 200, session creation via the raw API succeeds, and the returned webSocketDebuggerUrl accepts a raw WebSocket upgrade directly — so the break is inside agent-browser's own Browser Use connect path, not the account or network. Treat one 400 Bad Request from -p browseruse as a known failure signal, not a transient blip — do not retry it, fall straight to Kernel.

# Example: Browser Use (do NOT print the key)
source "$HOME/.config/agent-browser-browseruse.env"   # if present
# If BROWSER_USE_API_KEY empty → ask user for the key; write to that env file (chmod 600); source; retry
# If it returns "CDP WebSocket connect failed: HTTP error: 400 Bad Request" → known-broken on this host, skip to Kernel

SESSION="prov-$(agent-browser session id --scope cwd --prefix task)"
env -u AGENT_BROWSER_PROVIDER \
  agent-browser --session "$SESSION" -p browseruse \
  open https://example.com

Always pass -p <name> explicitly in commands (do not rely on a sticky global AGENTBROWSERPROVIDER for the whole session — it breaks Steel/CDP later). Never combine -p with --cdp.

If no provider key exists: ask the user which provider they want and for the API key (or dashboard invite). Offer to:

• write ~/.config/agent-browser-<provider>.env (chmod 600) and a guarded ~/.zshrc source line;
• open the provider dashboard URL from references/providers.md;
• re-run the failed step after config.

Do not invent keys. Do not paste key values into chat, commits, or logs — confirm with "key present / length only."

Tier 4 — still blocked

Ask for one of, then configure and retry from the matching tier:

1. A CDP websocket URL (ws:// / wss://) or host:port for an existing Chrome
2. A provider name + API key (Browser Use / Kernel / Browserless / Browserbase)
3. Approval to install local Chrome / agent-browser (npm i -g agent-browser, agent-browser install)
4. Approval to deploy self-hosted Steel (this fleet: Coolify compose under deploy/steel-browser/)

Core interaction loop (any tier)

Use the same runtime prefix on every command in the flow:

# PREFIX is tier-1 env -u … --session … --args …   OR tier-2 … --cdp …   OR tier-3 … -p <name>
$PREFIX open https://example.com
$PREFIX snapshot -i          # refs like @e3 — never @ref=e3
$PREFIX click @e3
$PREFIX wait --url "**/expected"
$PREFIX snapshot -i          # refs stale after navigation — always re-snapshot
$PREFIX get url
$PREFIX get title
$PREFIX errors
$PREFIX close

Verify outcomes separately from action success. Screenshots when visual proof matters.

Helpers

Output contract

Report: final URL/title + user-visible outcome; which tier ran (and any escalation); session name; deterministic checks; cleanup performed (incl. Steel sessions/release if used); artifacts + sensitivity; credentials requested or files written (names only, never values); any install/deploy recommendation left for the user.