open source · apache-2.0 · the validation layer for AI agents
Plain English in.
Real browser proof out.
BrowserBash is the free, open-source validation layer for AI agents: plain-English tests, a real Chrome, and a verdict that is an exit code, not a vibe. Your coding agent plugs in over MCP with one line, and it all runs on free local models (Ollama), zero API keys.
$ npm install -g browserbash-cli100% free to use. Install the CLI and automate in seconds — no signup needed to run. Create a free account for the dashboard: run history, video recordings and per-run replay.
100% free · no API keys · open source
Describe a test.
Watch AI run it.
BrowserBash turns one plain-English sentence into a real browser test — no selectors, no code, no flaky locators — and hands your AI agent a machine-readable verdict over MCP or NDJSON. Free local models (Ollama), zero API keys, no credit card. Open source, Apache-2.0.
$ npm install -g browserbash-cliFree forever for the CLI — install and automate any site in seconds. A free account adds a dashboard with run history, video recordings and per-run replays.
plain English in · real browser out
demo
Watch a run, line by line
One objective in, NDJSON events out — the same stream your CI and AI agents consume.
Prefer to just watch a full run?
One sentence in, a real Chrome driven start to finish, green ✓ PASSED out, about fifteen seconds.
$ npm install -g browserbash-clifor AI agents
Your coding agent builds it. BrowserBash proves it works.
Claude Code, Cursor, Codex or any MCP host plugs BrowserBash in with one line and gets three tools: run an objective, run a test file, run a whole suite. Every call returns a structured verdict, so "did my change break the checkout?" becomes a tool call, not a guess.
$ claude mcp add browserbash -- browserbash mcpMCP server built in
browserbash mcp serves run_objective, run_test_file and run_suite on stdio. No extra install, no cloud relay, nothing leaves your machine.
Verdicts, not vibes
status, summary, extracted values, deterministic assertion results and cost land in one JSON object. Exit codes 0/1/2/3 for shell agents.
Deterministic assertions
Verify steps compile to real Playwright checks with no model in the loop — expected vs actual evidence on every failure, agent-judged checks clearly flagged.
NDJSON for everything else
Not on MCP? --agent streams one JSON event per line with a stable, additive schema. Same contract since v1.0.
Budgets your platform team will sign off
cost_usd per run, --budget-usd per suite: spend stops the suite, skipped tests are reported, nothing runs away overnight.
Warm runs cost nothing
The replay cache re-runs green tests with zero model calls, so agents can validate after every edit without burning tokens.
try it
Pick an objective, watch Bo work
Replays of real CLI output. Copy any command and run it on your machine — that's the whole product.
how it works
Three layers, all swappable
1 · Provider
Where does the browser run?
local— your Chrome (default)cdp— any DevTools endpointbrowserbase— cloud browserslambdatest— TestMu gridbrowserstack— Automate grid
2 · Engine
Who interprets the English?
stagehand— MIT OSS by Browserbase (default)builtin— Anthropic tool-use loop, auto-selected for cloud grids
3 · LLM
Who does the thinking?
- Ollama first — local, free, no keys
- Anthropic / OpenAI / Google via flags
- Any OpenAI-compatible server (vLLM, LM Studio)
ollama pull qwen3 && browserbash run "…"Stagehand (MIT) + local Chromium + Ollama — zero cloud cost, no API keys.features
Built for agents and CI, friendly to humans
Open source first
Apache-2.0 CLI on an MIT engine. The default path costs nothing and phones no one.
Markdown tests, now with real assertions
Committable *_test.md files with @import, API steps for data seeding, and Verify steps that run as deterministic Playwright checks.
Log in once, reuse everywhere
browserbash auth save captures a login session; --auth replays it in every test. No more re-login per test, no rate-limit walls in CI.
Record and import
Click through a flow once and get a plain-English test. Or point browserbash import at your Playwright suite and review the generated twins.
Parallel, sharded, budgeted
run-all schedules by real memory, splits across CI machines with --shard, runs viewport matrices, and hard-stops at --budget-usd.
Monitor what you test
The same test doubles as a production check: browserbash monitor --every 10m alerts your Slack only when pass flips to fail.
why browserbash
Free. Open source. No lock-in.
Other AI browser tools want a credit balance or their cloud. BrowserBash is free and open source — run it with no account, no API keys, no meter. An account is optional, only for the dashboard.
Zero signup to run
npm install and automate in sixty seconds — no account needed for the CLI. A free dashboard account is optional, for run history and recordings.
Open source all the way down
Apache-2.0 with the full agent loop in the repo. Read it, fork it, fix it — not just the README.
Your models, your machine
Local Ollama by default — free, private, unmetered. Or bring an Anthropic or OpenRouter key and swap models with one flag.
Cloud-neutral by design
Browserbase, LambdaTest, BrowserStack or your own Chrome. Use the grid your team already pays for.
Private by default
Runs never leave your machine unless you add --upload. Nothing phones home on its own.
Built for CI, not demos
Natural-language E2E test automation with exit codes your pipeline already understands.
case study
We pointed it at our own Playwright suite
The Testing Academy runs a production Playwright + TypeScript framework against TTACart. We rewrote its end-to-end checkout — login, cart, checkout, confirmation — as one plain-English file and ran it with a single command on a free local model. Same journey, session held to the end, recorded for replay.
6 page objects → 1 file
The full login-to-checkout journey, rewritten as one committable *_test.md — no selectors, no page objects.
Session held to the end
The AI agent keeps the logged-in session alive from the first step through the order confirmation screen.
$0 on a local model
Ran on a local Ollama model — no API key, no grid, nothing leaving the machine. Captured with --record.
github.com/PramodDutta/AdvancePlaywrightFramework1x → plain EnglishHow we rewrote the suite, ran it with one command, and replayed it in the dashboard.new in 1.5.0
The validation-layer release, just shipped
Everything below is live in the free CLI today: npm install -g browserbash-cli. Built in the open, shipped to everyone, no paid gate on anything that runs on your machine.
MCP server
browserbash mcp plugs the whole CLI into Claude Code, Cursor, Codex and any MCP host as three validation tools. One line, zero dependencies.
testmd v2: per-step execution
version: 2 files run step by step on one browser session: API steps seed data over plain HTTP, Verify steps assert deterministically, English steps drive the agent.
Deterministic Verify assertions
Nine grammar forms compile to real Playwright checks. A pass means the condition held; a fail ships expected-vs-actual evidence in run_end.assertions.
Saved logins (auth save / --auth)
Log in once in a visible browser, reuse the session across every run, suite and monitor. Stored 0600, origin-checked, secrets never printed.
Monitor mode + webhooks
browserbash monitor runs a test on an interval and alerts Slack or any webhook only on pass/fail changes. Warm cache makes it nearly token-free.
Budgets and cost visibility
cost_usd on every run, --budget-usd / --budget-tokens on suites: crossing the budget stops new launches, reports the rest as skipped and exits 2.
Sharding + viewport matrix
--shard 2/4 splits a suite deterministically across CI machines; --matrix-viewport runs every test per viewport with labeled results.
Playwright import
browserbash import converts your existing specs to plain-English tests heuristically and writes an honest IMPORT-REPORT.md for whatever it could not translate.
Flow recorder
browserbash record captures a click-through in a real browser and writes the test file. Password values never leave the page.
quick start
From zero to your first run in 3 steps
All free. No credit card, no paid API keys.
Install the CLI
One line from npm. Free and open source.
npm install -g browserbash-cli
Run with a free model
Local Ollama or a free OpenRouter model — no keys.
ollama pull qwen3 browserbash run "Open example.com and store the heading as 'h1'"
Create a free account
Connect once, then see every run, recording and replay on your dashboard.
browserbash connect --key bb_... browserbash run "..." --record --uploadCreate free account →