Browserbash

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](https://browserbash.com) · [Docs / Learn](https://browserbash.com/learn) · [Tutorials](https://browserbash.com/tutorials) · [npm](https://www.npmjs.com/package/browserbash-cli)

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/ — 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/

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

• Concurrency is auto-derived from CPU and free memory (min(requested, cpus, floor((mem - 2GB) / budget))), so big suites do not thrash the machine. Override with --concurrency, tune the estimate with --memory-budget . A hard watchdog also kills any test whose whole process tree (Node + Chromium) exceeds --memory-cap (default 2x the budget, 0 disables); the test is reported as an infra error with a test_kill event, and retried per --retries.
• Each test runs as an isolated child process with its own Result.md; a failure never leaks state to the next test.
• --retries retries infra errors only (not real failures), --max-failures stops early, --stagger softens burst load.
• Outputs: a merged NDJSON stream (--events, add --agent to also stream on stdout), JUnit XML (--junit), and a RunAll-Result.md with a flaky column.
• Run history in .browserbash/memory/history.json orders the next run (previously-failed first, then slowest first) and flags flaky tests. --no-memory opts out.
• Sharding: --shard 2/4 runs a deterministic slice, computed on sorted discovery order so parallel CI machines agree without coordination.
• Viewport matrix: --matrix-viewport 1280x720,390x844 runs every test once per viewport; cells are labeled in events, JUnit and results. Single runs take --viewport WxH too.
• Budgets: --budget-usd 2.50 (or --budget-tokens) stops launching new tests once estimated spend crosses the budget; the rest are reported skipped and the suite exits 2. Spend lands in RunAll-Result.md and JUnit .
• Webhooks: --notify POSTs the suite verdict when it ends (Slack URLs get Slack formatting).
• Exit code: 0 all passed · 1 any failed · 2 infra error or budget stop · 3 suite timeout.

Cheap-model routing

Plan on a strong model, execute on a cheap one, escalate back automatically after a failed step:

browserbash run "..." --model claude-opus-4-8 --model-exec claude-haiku-4-5

run_end reports tokens_in / tokens_out (builtin engine) so you can see what a run costs, plus a cost_usd estimate from a bundled per-model price table (override at ~/.browserbash/pricing.json; unknown models get no estimate rather than a wrong one). Set persistently with config set routing.executionModel .

Test files (*_test.md)

Committable, reviewable Markdown tests:

# Login flow

• Open {{base_url}}/l