browserbash

BrowserBash

使用简单英语进行浏览器自动化。无需选择器。免费且开源。

你只需用简单英语写下目标。AI Agent 会逐步操控真实的 Chrome 浏览器——无需选择器，无需脚本。优先使用 Ollama，因此可通过免费的本地模型运行，无需 API 密钥，任何内容都不会离开你的设备。

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

网站 · 文档 / 学习 · 教程 · npm

---

这两层都可替换：引擎负责理解英语，提供方负责运行浏览器。

引擎（负责理解英语的组件）

引擎	介绍	许可证
stagehand（默认）	Stagehand——由 Browserbase 开发的开源 AI 浏览器自动化框架。提供 act/extract/observe/agent 基础功能、自我修复能力，并支持 Anthropic/OpenAI/Google 模型。	MIT
builtin	在代码库中实现的 Anthropic 工具调用循环，由 Playwright 驱动。当 Stagehand 无法连接到网格（如 LambdaTest、BrowserStack）时会自动使用。	Apache-2.0

提供方（浏览器的运行位置）

提供方	浏览器的运行位置	引擎	身份验证
local（默认）	此设备上的 Chromium/Chrome	stagehand 或 builtin	无
cdp	任意 Chrome DevTools Protocol 端点（你的网格、docker、由 Playwright MCP 管理的浏览器）	stagehand 或 builtin	无
browserbase	Browserbase 云浏览器	仅 stagehand	BROWSERBASE_API_KEY / BROWSERBASE_PROJECT_ID
lambdatest	LambdaTest / TestMu AI 云网格	builtin（自动）	LT_USERNAME / LT_ACCESS_KEY
browserstack	BrowserStack Automate 云网格	builtin（自动）	BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY

大模型后端（负责思考的组件）——优先开源

默认模型为 auto，按以下顺序解析：

1. 本地运行的 Ollama → ollama/<OLLAMA_MODEL or first installed model>——免费、开源，无需密钥
2. 已设置 ANTHROPIC_API_KEY → claude-opus-4-8
3. 已设置 OPENAI_API_KEY → openai/gpt-4.1
4. 否则：显示设置指引并报错

后端	模型标志	所需条件
Ollama——本地、免费、开源软件（首选）	auto 或 ollama/<model>，例如 ollama/qwen3	Ollama 正在运行；可通过 OLLAMA_BASE_URL 覆盖 http://localhost:11434/v1，通过 OLLAMA_MODEL 固定自动检测的模型。同一标志也适用于任何兼容 OpenAI 的服务（vLLM、LM Studio、llama.cpp）。
Anthropic	claude-opus-4-8	ANTHROPIC_API_KEY
OpenAI / Google	openai/gpt-4.1、google/gemini-2.5-flash	提供方密钥（Stagehand 引擎）
OpenRouter——数百种模型，一个密钥	openrouter/<vendor>/<model>，例如 openrouter/anthropic/claude-sonnet-4-6、openrouter/meta-llama/llama-3.3-70b-instruct	OPENROUTER_API_KEY (https://openrouter.ai/keys)；使用 OPENROUTER_BASE_URL 覆盖端点
兼容 Anthropic 的网关	claude-* + ANTHROPIC_BASE_URL	builtin 引擎通过任意兼容 Anthropic 的端点路由（例如，代理本地模型的 LiteLLM 代理）

完全免费的开源技术栈（默认）

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

Stagehand 引擎（MIT）+ 本地 Chromium + Ollama（MIT）——零云端成本，无需 API 密钥。提示：小模型（≤8B）处理多步目标时表现不稳定；Qwen3 / Llama 3.3 70B 级别的模型效果最佳。

注意：云网格提供方（lambdatest、browserstack）使用 builtin 引擎，该引擎使用 Anthropic API——请搭配 ANTHROPIC_API_KEY 或 ANTHROPIC_BASE_URL 网关。

安装

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

需要 Node ≥ 18 和稳定版 Google Chrome（用于 local 提供方）。

快速开始

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 模式（适用于 AI 编码工具和 CI）

--agent 会将标准输出切换为 NDJSON，每行一个 JSON 对象，且架构稳定：

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

• 进度事件：{"type":"step","step":1,"status":"passed","action":"navigate","remark":"...","cached":false}
• 终止事件：{"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":"..."}

退出代码：0 通过 · 1 失败 · 2 错误 · 3 超时。cached、cache、tokens_in/tokens_out 是增量字段（在相关时出现），因此不会影响现有使用方。

完整的 Agent 集成指南：docs/agents.md。

MCP 服务（Agent 可原生使用 BrowserBash）

BrowserBash 是 AI Agent 的验证层：你的编码 Agent 构建功能，BrowserBash 则在真实浏览器中证明它可用。一行命令即可将其接入任何 MCP 主机：

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

提供的工具：run_objective（一个自然语言目标）、run_test_file（一个 *_test.md）、run_suite（一个文件夹，并行执行）。每个工具都会返回结构化的判定 JSON：status、summary、final_state、assertions、cost_usd、duration_ms。测试失败也代表验证成功，因此工具调用会成功，Agent 可读取判定结果。无需额外依赖，仅使用 stdio，数据不会离开你的计算机。

仪表板

每次运行都会保存在磁盘上的私有存储中（~/.browserbash/runs，密钥经过屏蔽，最多保留 200 条）。有两种查看方式：

本地仪表板 — 免费、无需账户、完全本地运行：

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

左侧面板列出你的运行记录；主面板显示判定结果、提取的值和录制内容 — 使用 --record 可获得屏幕截图和会话视频（stagehand 引擎，视频需要 ffmpeg，已随附），或获得可在 trace.playwright.dev 上打开的原生 Playwright 跟踪（builtin 引擎）。数据不会离开你的计算机。

**云端仪表板 — 可选，每次运行单独选择是否启用：**托管仪表板位于 browserbash.com/dashboard，可跨计算机查看运行历史记录，并为每次运行生成可分享的页面。

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

不使用 --upload 就不会向云端发送任何内容。BrowserBash 免费且开源；云端运行记录会保留 15 天。

回放缓存（热运行跳过模型调用）

一次通过的运行会记录执行过的操作。下次运行内容相同时，会在零模型调用的情况下回放这些操作，只有页面实际发生变化时，Agent 才会介入。稳定运行后的测试套件，速度和成本都接近脚本运行。

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 会报告 hit / miss / off。默认启用；使用 config set cache.enabled false 可禁用，使用 cache.dir 可更改位置（默认值为 .browserbash/cache，由 init 添加到 gitignore）。密钥绝不会进入缓存：值通过变量通道传入（Stagehand），或重新模板化为 {{name}} 令牌（builtin）；任何会输入密钥的缓存操作都会绑定来源站点 — 在不同来源站点上回放时会安全失败。Builtin 日志也会使用每台计算机独有的密钥进行 HMAC 签名（~/.browserbash/cache.key）；被编辑过或来自其他计算机的日志会被忽略，并直接重新记录。希望共享已提交缓存的 CI 集群，可在每个运行器上设置相同的 BROWSERBASH_CACHE_KEY（64 个十六进制字符）。

并行套件（run-all）

使用内存感知调度，一次运行整个文件夹中的 *_test.md 文件：

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

• 并发数会根据 CPU 和可用内存自动计算（min(requested, cpus, floor((mem - 2GB) / budget))），避免大型套件让机器不堪重负。可用 --concurrency 覆盖，并通过 --memory-budget <mb> 调整估算值。硬性监控器还会终止整个进程树（Node + Chromium）超过 --memory-cap <mb> 的任何测试（默认值为预算的 2 倍，0 表示禁用）；此类测试会作为基础设施错误报告，并附带 test_kill 事件，随后按照 --retries 重试。
• 每项测试都在隔离的子进程中运行，并有自己的 Result.md；一次失败不会将状态泄漏给下一项测试。
• --retries <n> 仅重试基础设施错误（不重试实际失败），--max-failures <n> 可提前停止，--stagger <ms> 可减轻突发负载。
• 输出：合并后的 NDJSON 流（--events，添加 --agent 还会同步输出到标准输出）、JUnit XML（--junit），以及包含易失败列的 RunAll-Result.md。
• .browserbash/memory/history.json 中的运行历史会决定下一次运行的顺序（先运行之前失败的测试，再运行最慢的测试），并标记易失败的测试。使用 --no-memory 可选择退出。
• 分片：--shard 2/4 会运行一个确定性分片，按排序后的发现顺序计算，因此并行 CI 机器无需协调即可保持一致。
• 视口矩阵：--matrix-viewport 1280x720,390x844 会针对每个视口运行每项测试；事件、JUnit 和结果中都会标记对应单元格。单次运行也可使用 --viewport WxH。
• 预算：--budget-usd 2.50（或 --budget-tokens）会在预计花费超出预算后停止启动新测试；其余测试会报告为 skipped，套件以 2 退出。花费信息会写入 RunAll-Result.md 和 JUnit <properties>。
• Webhook：--notify <url> 会在套件结束时 POST 套件结果（Slack URL 会使用 Slack 格式）。
• 退出码：0 全部通过 · 1 有任何失败 · 2 基础设施错误或预算中止 · 3 套件超时。

低成本模型路由

使用强模型制定计划，用低成本模型执行；步骤失败后会自动切回强模型：

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

run_end 会报告 tokens_in / tokens_out（内置引擎），让你了解一次运行的成本；还会根据随附的每模型价格表估算 cost_usd（可在 ~/.browserbash/pricing.json 覆盖；对于未知模型，不提供估算，而不会给出错误估算）。使用 config set routing.executionModel <id> 可持久设置。

测试文件（*_test.md）

可提交、可审查的 Markdown 测试：

# Login flow

- Open {{base_url}}/login
- Type {{username}} into the email field
- Type {{password}} into the password field and press Enter
- Verify the dashboard heading is visible
- Store the logged-in user name as 'user_name'

browserbash testmd run ./.browserbash/tests/login_test.md --provider browserstack

通过 @import ./helpers/login.md 组合内容（步骤会插入到对应位置）。每次运行后，测试文件旁都会生成一个 Result.md。

testmd v2：不会误报的断言和 API 步骤

添加 version: 2 frontmatter 后，步骤会在单个浏览器会话中逐条执行，并支持两种不会触及模型的确定性步骤类型：

---
version: 2
auth: staging
---
# Checkout with seeded data

- POST {{base_url}}/api/seed with body {"sku": "tshirt-red"}
- Expect status 201, store $.order.id as 'order_id'
- Open {{base_url}}/cart
- Click the checkout button
- Verify the URL contains 'checkout'
- Verify the 'Thank you for your order!' heading is visible
- Verify stored 'order_id' equals '{{expected_id}}'

• API 步骤（GET/POST/PUT/DELETE/PATCH url [with body {...}] + Expect status N[, store $.path as 'name']）会以纯 HTTP 方式运行：先准备种子数据，再通过 UI 验证。存储的值可在后续步骤中作为 {{variables}} 使用。
• Verify 步骤会编译为实际的 Playwright 检查（URL 包含指定内容、标题是/包含指定内容、文本可见、'name' button|link|heading 可见、元素计数、存储值相等）。通过表示条件成立；失败时，run_end.assertions 和 Result.md 断言表中会提供预期值与实际结果证据。不符合语法的 Verify 行仍会运行，由 Agent 判断并标记为 judged: true。
• 连续的纯英文步骤会作为分组 Agent 区块在同一页面上运行，因此登录状态和导航会延续。
• v1 文件（无 frontmatter）的行为与之前完全一致。目前，v2 由内置引擎驱动（需要 ANTHROPIC_API_KEY 或 ANTHROPIC_BASE_URL 网关）。

变量

{{key}} 占位符会在目标和测试步骤中替换。加载顺序（最后一项优先级最高）：

1. 全局：~/.browserbash/variables/*.json
2. 项目：./.browserbash/variables/*.json
3. --variables-file <path>
4. --variables '<json>'

将敏感值标记为 {"value": "...", "secret": true}——它们在所有日志和 NDJSON 输出中都会显示为 *****。

已保存的登录信息（browserbash auth）

实际测试套件通常需要登录后才能访问。登录一次，即可在各处重复使用会话：

browserbash auth save staging --url https://app.example.com/login   # log in, press Enter
browserbash run "Open the dashboard and store the balance as 'balance'" --auth staging
browserbash run-all .browserbash/tests --auth staging               # every test, no re-login
browserbash auth list && browserbash auth delete staging

会话是保存在 ~/.browserbash/auth/ 中的 Playwright storageState 文件（权限模式为 0600，文件包含有效凭据）。测试文件可以通过 frontmatter 中的 auth: staging 固定使用自己的配置文件。如果某个配置文件中已保存的来源不涵盖目标 URL，系统会发出警告，而不是悄无声息地不做任何操作。

无需编写测试即可创建测试

# Record: click through the flow once in a real browser, get a test file
browserbash record https://app.example.com --out .browserbash/tests/checkout_test.md

# Import: convert an existing Playwright suite to plain English
browserbash import ./e2e --out-dir .browserbash/imported

record 会记录点击、输入和导航（密码值不会离开页面；生成的步骤会读取 Type {{password}} into ...）。import 会确定性地转换常见的 Playwright 调用，并将所有无法转换的内容写入 IMPORT-REPORT.md，而不是猜测。两种方式生成的内容都是供你审阅的起点，并非绝对可靠。

监控（browserbash monitor）

同一批测试也可用作生产环境检查：

browserbash monitor .browserbash/tests/checkout_test.md --every 10m \
  --notify https://hooks.slack.com/services/T0/B0/xyz

只有状态从通过变为失败或从失败变为通过时才会触发告警，不会在每次成功运行时触发。Slack webhook URL 会使用 Slack 格式；其他任何 URL 都会收到原始 JSON 负载。重放缓存预热后，在页面实际发生变化前，监控不会调用任何模型。

配置

browserbash init                          # scaffold ./.browserbash/
browserbash config show
browserbash config set defaultProvider lambdatest
browserbash providers                     # list providers
browserbash login --provider lambdatest --username "$USER" --access-key "$KEY"
browserbash whoami

优先级：标志 > 环境变量 > ~/.browserbash/config.json 默认值。

CI 配置示例（GitHub Actions）

- run: npm ci && npm run build
- run: |
    node dist/index.js login --provider lambdatest --username "$LT_USERNAME" --access-key "$LT_ACCESS_KEY"
    node dist/index.js testmd run .browserbash/tests/smoke_test.md --agent --headless --timeout 180
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    LT_USERNAME: ${{ secrets.LT_USERNAME }}
    LT_ACCESS_KEY: ${{ secrets.LT_ACCESS_KEY }}

进程退出代码即为测试结果——无需解析输出。

也可以使用官方 GitHub Action（PR 结果评论、构建产物、分片矩阵作业、预算停止）：

- uses: PramodDutta/browserbash@main
  with:
    tests: .browserbash/tests
    budget-usd: '2.00'
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

完整指南：docs/github-action.md。

架构

src/
├── index.ts            # CLI (commander): run, testmd, run-all, monitor, auth, record, import, mcp, ...
├── runner.ts           # engine routing + provider session + replay cache + vendor status reporting
├── engine/
│   ├── stagehand.ts    # default engine: Stagehand agent (stagehand.dev, MIT) — LOCAL / cdpUrl / Browserbase
│   ├── agent.ts        # builtin engine: Anthropic tool-use loop (manual loop → NDJSON step events)
│   ├── tools.ts        # builtin browser tools: navigate, snapshot, click, type_text, wait_for, extract, done
│   ├── assertions.ts   # deterministic Verify grammar + executor (no model in the loop)
│   ├── replay.ts       # builtin replay-first cache: replay recorded actions, origin-pinned
│   └── routing.ts      # per-model thinking config + cheap-exec model routing
├── providers/          # vendor abstraction — add a new vendor by implementing BrowserProvider
│   ├── types.ts        # BrowserProvider / ProviderSession + context options (auth, viewport)
│   ├── local.ts        # system Chrome
│   ├── cdp.ts          # attach to any CDP endpoint (incl. Playwright MCP browsers)
│   ├── lambdatest.ts   # LambdaTest/TestMu grid + setTestStatus reporting
│   └── browserstack.ts # BrowserStack Automate grid + setSessionStatus reporting
├── orchestrator/       # run-all: memory-aware scheduler + child-process suite runner
│   ├── scheduler.ts    # concurrency formula, admission watermark, shard/matrix, JUnit
│   └── run-all.ts      # spawn children, aggregate NDJSON, verdicts, retries, budgets
├── mcp/server.ts       # MCP stdio server: run_objective / run_test_file / run_suite
├── testmd/             # parser (@import, frontmatter), v1 runner, v2 per-step runner + API steps
├── import/playwright.ts# heuristic Playwright spec -> *_test.md converter
├── record/             # interactive recorder: capture script + events -> English steps
├── monitor.ts          # interval checks, state-change alerts
├── auth-store.ts       # saved storageState profiles (~/.browserbash/auth)
├── pricing.ts          # cost_usd estimates (overridable price table)
├── notify.ts           # webhook payloads (Slack autodetect)
├── cache-store.ts      # builtin action-journal cache (re-templatized, origin-pinned, HMAC-signed)
├── memory-store.ts     # run history: ordering + flaky report
├── config.ts           # ~/.browserbash/config.json + credential resolution
├── variables.ts        # {{var}} substitution, secrets masking
└── output.ts           # NDJSON / human reporter

添加供应商 = 新建一个实现 BrowserProvider 的文件（connect() 返回 Playwright Browser/Page）+ 在 providers/index.ts 中添加一行注册项。

许可证

Apache-2.0