browserbash

BrowserBash

平易な英語でブラウザーを自動操作。セレクター不要。無料のオープンソースです。

平易な英語で目的を記述すると、AI エージェントが実際の 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	Playwright を操作する、リポジトリ内の Anthropic ツール使用ループです。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

LLM バックエンド（思考を担うもの）— オープンソースを優先

デフォルトのモデルは 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 — ローカル、無料、OSS（推奨）	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 — 数百のモデルを1つのキーで	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）は Anthropic API を使用する builtin エンジンで動作します。ANTHROPIC_API_KEY または ANTHROPIC_BASE_URL ゲートウェイと組み合わせてください。

インストール

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

Node ≥ 18 と Google Chrome stable が必要です（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

エージェントモード（AI コーディングツールと CI 向け）

--agent を指定すると、標準出力が NDJSON に切り替わります。安定したスキーマで、1 行につき 1 つの 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 は追加フィールドであり、該当する場合に出力されるため、既存のコンシューマーに影響しません。

エージェントとの統合に関する完全なガイド：docs/agents.md。

MCP サーバー（エージェントが BrowserBash をネイティブに利用）

BrowserBash はAI エージェント向けの検証レイヤーです。コーディングエージェントが機能を構築し、BrowserBash が実際のブラウザーで動作を検証します。1 行で、あらゆる MCP ホストに接続できます。

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

公開されるツール：run_objective（平易な英語で記述した目標を 1 つ実行）、run_test_file（*_test.md）、run_suite（フォルダー内を並列実行）。各ツールは、構造化された判定結果の JSON（status、summary、final_state、assertions、cost_usd、duration_ms）を返します。テストの失敗は検証の成功を意味するため、ツール呼び出し自体は成功し、エージェントが判定結果を確認します。追加の依存関係は不要で、stdio のみを使用し、データがマシンの外に出ることはありません。

ダッシュボード

すべての実行結果は、オンディスクのプライベートストアに保存されます（~/.browserbash/runs。シークレットはマスキングされ、保存数は最大 200 件）。確認方法は 2 つあります。

ローカルダッシュボード — 無料、アカウント不要、完全にローカル：

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 日間保存されます。

リプレイキャッシュ（ウォーム実行ではモデルを呼び出しません）

成功した実行では、実行した操作が記録されます。次回、同一の実行を行うと、モデルを一切呼び出さずに操作を再生し、ページに実際の変更があった場合にのみエージェントが介入します。定常状態のテストスイートは、スクリプトとほぼ同じ速度とコストで実行できます。

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 に追加されます）。シークレットがキャッシュに保存されることはありません。値は variables チャネル（Stagehand）経由で渡されるか、{{name}} トークンに再テンプレート化されます（builtin）。シークレットを入力するキャッシュ済み操作はすべてオリジンに固定されるため、別のオリジンで再生すると安全のため失敗します。builtin のジャーナルにも、マシンごとのキー（~/.browserbash/cache.key）で HMAC 署名が付与されます。編集されたジャーナルや別のマシンのジャーナルは無視され、再記録されます。コミット済みキャッシュを共有する CI フリートでは、すべてのランナーに同じ BROWSERBASH_CACHE_KEY（64 桁の 16 進文字列）を設定できます。

並列スイート（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 のフロントマターを追加すると、ステップは単一のブラウザーセッションで 1 つずつ実行されます。モデルに触れない、決定論的なステップタイプが 2 つあります。

---
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 行も実行されますが、エージェントによる判定となり、judged: true のフラグが付けられます。
• 連続する通常の英語のステップは、同じページ上でグループ化されたエージェントブロックとして実行されるため、ログイン状態とナビゲーションが維持されます。
• v1 ファイル（フロントマターなし）は、これまでとまったく同じ動作をします。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

アラートは pass<->fail の状態変化があった場合にのみ、どちらの方向でも発生します。正常な実行のたびに発生することはありません。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（Playwright の Browser／Page を返す connect() を実装）用のファイルを 1 つ追加し、providers/index.ts にレジストリ行を 1 つ追加します。

ライセンス

Apache-2.0