BrowserBash

Plain-English browser automation. No selectors. Free and open-source.

You write a plain-English objective. An AI agent drives a real Chrome browser step by step — no selectors, no scripts. Ollama-first, so it runs on free local models with no API keys and nothing ever leaves your machine.

npm install -g browserbash-cli
browserbash run "Open news.ycombinator.com and store the top story title as 'top_story'"

Website · Docs / Learn · Tutorials · npm

Both layers are swappable: the engine interprets the English, the provider runs the browser.

Engines (who interprets the English)

Providers (where the browser runs)

LLM backends (who does the thinking) — open source first

Default model is auto, resolved in this order:

1. Ollama running locally → ollama/<OLLAMA_MODEL or first installed model> — free, open source, no keys
2. ANTHROPIC_API_KEY set → claude-opus-4-8
3. OPENAI_API_KEY set → openai/gpt-4.1
4. otherwise: error with setup guidance

Fully free / open-source stack (the default)

ollama pull qwen3                 # or any tool-capable local model
browserbash run "Open https://example.com and store the heading as 'h1'"

Stagehand engine (MIT) + local Chromium + Ollama (MIT) — zero cloud cost, no API keys. Tip: small models (≤8B) are flaky on multi-step objectives; Qwen3 / Llama 3.3 70B class works best.

Note: cloud-grid providers (lambdatest, browserstack) use the builtin engine, which speaks the Anthropic API — pair them with ANTHROPIC_API_KEY or an ANTHROPIC_BASE_URL gateway.

Install

npm install
npm run build
npm link        # exposes the `browserbash` command

Requires Node ≥ 18 and Google Chrome stable (for the local provider).

Quick start

export ANTHROPIC_API_KEY=sk-ant-...

# One-shot objective, local browser, Stagehand engine (default)
browserbash run "Open https://news.ycombinator.com and store the top story title as 'top_story'"

# Browserbase cloud (Stagehand native)
export BROWSERBASE_API_KEY=... BROWSERBASE_PROJECT_ID=...
browserbash run "..." --provider browserbase

# Cloud grid (auto-switches to builtin engine)
export LT_USERNAME=... LT_ACCESS_KEY=...
browserbash run "..." --provider lambdatest --headless

# Attach to an existing browser (CDP / Playwright MCP)
browserbash run "..." --cdp-endpoint ws://localhost:9222/devtools/browser/<id>

# Force the builtin engine
browserbash run "..." --engine builtin

Agent mode (for AI coding tools & CI)

--agent switches stdout to NDJSON — one JSON object per line, stable schema:

browserbash run "<objective>" --agent --headless --timeout 120

• Progress events: {"type":"step","step":1,"status":"passed","action":"navigate","remark":"...","cached":false}
• Terminal event: {"type":"run_end","status":"passed|failed|error|timeout","summary":"...","final_state":{...},"duration_ms":...,"provider":"local","cache":"hit|miss|off","tokens_in":...,"tokens_out":...,"test_url":"..."}

Exit codes: 0 passed · 1 failed · 2 error · 3 timeout. cached, cache, tokens_in/tokens_out are additive fields (present when relevant), so existing consumers are unaffected.

Full agent integration guide: docs/agents.md.

MCP server (agents consume BrowserBash natively)

BrowserBash is a validation layer for AI agents: your coding agent builds a feature, BrowserBash proves it works in a real browser. One line plugs it into any MCP host:

claude mcp add browserbash -- browserbash mcp     # Claude Code
# Cursor / Windsurf / Zed / Codex: command "browserbash", args ["mcp"]

Tools exposed: run_objective (one plain-English objective), run_test_file (a *_test.md), run_suite (a folder, parallel). Each returns the structured verdict JSON: status, summary, final_state, assertions, cost_usd, duration_ms. A failed test is a successful validation, so the tool call succeeds and the agent reads the verdict. No extra dependencies, stdio only, nothing leaves your machine.

Dashboards

Every run is kept in a private on-disk store (~/.browserbash/runs, secrets masked, capped at 200). Two ways to see them:

Local dashboard — free, no account, fully local:

browserbash dashboard                 # serve http://localhost:4477 and open it
browserbash run "..." --record --dashboard   # run, then open the dashboard on this run
browserbash dashboard --clear         # wipe the local store

Left panel lists your runs; the main pane shows the verdict, extracted values and the recording — with --record you get a screenshot plus a session video (stagehand engine, video needs ffmpeg, bundled) or a native Playwright trace you can open at trace.playwright.dev (builtin engine). Nothing leaves your machine.

Cloud dashboard — optional, opt-in per run: a hosted dashboard at browserbash.com/dashboard with run history across machines and shareable per-run pages.

browserbash connect --key bb_...      # one-time, key from browserbash.com/dashboard
browserbash run "..." --record --upload   # push THIS run (verdict + recording) to the cloud

Without --upload nothing is sent to the cloud. BrowserBash is free and open source; cloud runs are kept 15 days.

Replay cache (warm runs skip the model)

A green run records the actions it took. The next identical run replays them with zero model calls, and the agent only steps back in when the page actually changed. Steady-state suites run at close to script speed and cost.

browserbash testmd run ./checkout_test.md            # run 1: records the journal
browserbash testmd run ./checkout_test.md            # run 2: replays, no model
browserbash testmd run ./checkout_test.md --no-cache      # ignore the cache for this run
browserbash testmd run ./checkout_test.md --refresh-cache # wipe this test's entry, re-record

run_end.cache reports hit / miss / off. On by default; config set cache.enabled false to disable, cache.dir to relocate (default .browserbash/cache, gitignored by init). Secrets never enter the cache: values arrive through the variables channel (Stagehand) or are re-templatized to {{name}} tokens (builtin), and any cached action that types a secret is origin-pinned — replaying it on a different origin fails closed. Builtin journals are also HMAC-signed with a per-machine key (~/.browserbash/cache.key); an edited or foreign journal is ignored and simply re-recorded. CI fleets that want to share committed caches can set the same BROWSERBASH_CACHE_KEY (64 hex chars) on every runner.

Parallel suites (run-all)

Run a whole folder of *_test.md files at once with memory-aware scheduling:

browserbash run-all .browserbash/tests --concurrency 8 --junit out/junit.xml