browser-gateway

browser-gateway

クラウドブラウザー向けのオープンなルーター。
お使いのあらゆるブラウザープロバイダーを振り分ける単一のエンドポイントです。自動フェイルオーバー、永続プロファイル、セッションのリプレイ、REST API、MCP サーバー、ダッシュボードを備えています。
Puppeteer、Playwright、Stagehand、browser-use、あらゆる MCP クライアントで、そのまま動作します。

     

ウェブサイト  ·  クイックスタート  ·  MCP  ·  プロファイル  ·  リプレイ  ·  REST API  ·  ダッシュボード  ·  Discord

---

概要

単一のエンドポイント。複数のプロバイダー。プロバイダーが飽和状態になったり停止したりした場合は、自動的にフェイルオーバーします。

アプリは ws://gateway:9500/v1/connect に接続します。ゲートウェイは、ヘルス状態、容量、ルーティング戦略に基づいて、最適な利用可能プロバイダーを選択します。プロバイダーには、クラウド CDP サービス、Docker コンテナー、ローカルの Chrome インスタンスを指定できます。

---

ダッシュボード

すべてのインストールに Web ダッシュボードが付属します。ゲートウェイの起動後、http://localhost:9500/web を開いてください。

概要。 アクティブなセッション数、キューの深さ、プロバイダーの状態、接続エンドポイント、Puppeteer、Playwright、Stagehand、browser-use、raw CDP 用のコピー＆ペースト可能なクイックスタートを確認できます。

REST API。 フォーム形式の UI から、スクリーンショット、コンテンツ抽出、構造化スクレイピングのエンドポイントを実行できます。プロファイルの選択やパラメーターのリファレンスもインラインで確認できます。

プレイグラウンド。 ブラウザーから任意のプロバイダーをリアルタイムで操作できます。プロバイダーとプロファイルを選択し、ローカルブラウザーのようにキャンバスに入力すると、リモートセッションをリアルタイムで確認できます。

---

機能

ルーティングと信頼性

• 自動フェイルオーバー - 1 つのプロバイダーに障害が発生すると、クライアント側の変更なしで次のプロバイダーに即座に切り替わります
• 5 種類の負荷分散戦略 - 優先順位順、ラウンドロビン、最小接続数、レイテンシー最適化、重み付け
• プロバイダーごとの同時実行数制限 - ゲートウェイはすべてのバックエンドで maxConcurrent を適用します
• リクエストキュー - すべてのプロバイダーが過負荷の場合、即座に失敗するのではなく、接続を待機させます
• クールダウン - 障害が発生したプロバイダーはスキップされ、TTL の経過後に自動的に復旧します
• ヘルスチェック - 定期的な接続確認により、クライアントが接続する前にプロバイダーを異常状態としてマークします
• グレースフルシャットダウン - SIGTERM と SIGINT の受信時に、アクティブなセッションを正常に終了します
• セッションの再接続 - 切断されたクライアントは ?sessionId=<X-Session-Id> を指定して再接続できます。再開トークンを発行するプロバイダー（再開ウィンドウが有効な browserserve など）では、ページ、Cookie、ストレージを保持した同じブラウザーに再接続します。それ以外の場合は、同じプロバイダー上で新しいブラウザーを起動します
• Webhook - プロバイダーの停止、復旧、キューのオーバーフロー時にイベントを送信します

REST API

• スクリーンショット - POST /v1/screenshot は、任意の URL を PNG または JPEG で返します。ページ全体またはセレクターで指定した範囲を取得できます
• コンテンツ抽出 - POST /v1/content は、Markdown、プレーンテキスト、HTML、または整形済みの記事を返します
• スクレイピング - POST /v1/scrape は、CSS セレクターまたはページ全体の形式を使って構造化データを抽出します
• プールされたセッション - データベースのコネクションプールのように、ブラウザー接続を複数のリクエスト間で再利用します
• 自動リトライ - 失敗したリクエストを新しいページで再試行します

プロファイル — ブラウザーの状態を永続化

• セッション間で保持 - ページを離れるときと切断時に Cookie と localStorage を取得し、同じ ID で次回接続したときに復元します（browserserve では IndexedDB も対象です）
• どのプロバイダーでも保存 - すべてのプロバイダーで、任意のプロファイルを読み込み、保存できます。プロバイダーを特定のプロファイルに固定すると、そのプロファイルのセッションがそこにルーティングされます
• プロファイルは混在しません - 別のプロファイルの状態が残っているブラウザーは拒否されます。プロファイルなしのセッションで再利用されたブラウザーにほかのデータが残っている場合は、プロファイルとともに保存されます
• 1 行で有効化 - WebSocket URL に ?profile=acme を追加するだけで、あとは自動です
• 保存時に暗号化 - エンベロープ暗号化、入れ替え防止バインディング、scrypt 由来の KEK を使用した AES-256-GCM
• プロバイダーに依存しません - 状態は CDP レベルで取得されるため、どのプロバイダーでも復元できます
• プロファイルごとにロック - 同じ ID への同時接続には HTTP 409 を返し、データの破損を防ぎます
• エクスポートとインポート - 暗号化された .bgp ファイルは、異なるゲートウェイのインストール間で移行できます
• ワンクリックで有効化 - ダッシュボードのウィザードでブラウザー内に強力なキーを生成し、設定に書き込みます

詳しいガイド、セキュリティモデル、REST エンドポイント、制限事項については、プロファイルのドキュメントをご覧ください。

セッションのリプレイ — エージェントが見たものを確認

• フレーム単位で正確な映像記録 - CDP Page.startScreencast を使用して、ルーティングされたすべてのセッションを記録します
• インジェクションなし - 顧客のページ内ではスクリプトを実行せず、完全に帯域外でキャプチャします
• プロバイダーに依存しません - ページのスクリーンキャストに対応するすべてのバックエンドで動作します
• ダッシュボードプレーヤー - 記録したフレームをスクラブ再生し、キャプチャしたブラウザーのターゲットを切り替えられます
• 保持期間の設定 - 保持期間、セッションごとのバイト数上限、毎日のクリーンアップを設定できます

ストレージの構成、REST エンドポイント、調整可能な設定については、リプレイのドキュメントをご覧ください。

AI エージェント向け MCP サーバー

• 1 回の呼び出しで使えるツール - fetch_page は任意の URL を Markdown として読み込み、screenshot_page はそのページをキャプチャします。それぞれの呼び出しでブラウザーを開き、閉じます
• セッションツール - browser_session、browser_navigate、browser_snapshot、browser_act、browser_extract、browser_screenshot、browser_wait、browser_tabs、browser_evaluate、browser_observe を使って、ログイン、フォーム入力、複数ステップの作業を行えます
• コーディングエージェント向けのフォールバック - Claude Code プラグインは、組み込みの Web 取得がブロックされる場合、結果が空の場合、または JavaScript が必要な場合に、Claude から fetch_page を呼び出します（/plugin marketplace add browser-gateway/browser-gateway）。Codex、Cursor、Gemini CLI の設定については、plugins/browser-gatewayをご覧ください
• 設定不要 - Chrome を自動検出し、最初のツール使用時に起動します
• 並行セッション - 各エージェントに専用のブラウザーが割り当てられ、状態は共有されません
• 生の CDP - Playwright や Puppeteer への依存はありません
• 互換性 - Claude Code、Cursor、および MCP 互換クライアントで使用できます

Claude と Gemini のコンピューター操作

• モデル自身のブラウザーツールで任意のブラウザーを使用 - ゲートウェイ配下の任意のプロバイダーで、Claude のブラウザー操作ツールとコンピューター操作ツール、および Gemini のコンピューター操作を実行します
• 約 10 行 - runClaudeLoop / runGeminiLoop が、独自のモデル呼び出しを受け取り、操作、スクリーンショット、結果を処理します
• 安全なデフォルト設定 - http と https のみ許可し、プライベートネットワークをブロックします。サイトの許可リストは任意で設定でき、危険な操作では Gemini の確認ステップを使用します
• 追加の依存関係なし - browser-gateway/agent-tools/computer-use。Node.js、Bun、Deno、Cloudflare Workers ランタイムでテスト済みです

管理

• ダッシュボード - ブラウザーからプロバイダーの管理、セッションの監視、設定の編集ができます
• プロバイダーの CRUD - ダッシュボードまたは API からプロバイダーの追加、編集、削除、テストができます
• 設定エディター - 構文強調表示と検証機能を備えたブラウザー内エディターで gateway.yml を編集できます
• 認証 - トークンベースで、ダッシュボードには安全な HttpOnly Cookie を使用します
• プロトコルに依存しません - Playwright、Puppeteer、および任意の WebSocket プロトコルで動作します

---

クイックスタート

WebSocket プロキシとして（アプリケーション向け）

npm install -g browser-gateway

gateway.yml を作成します。

version: 1

providers:
  primary:
    url: wss://provider.example.com?token=${PROVIDER_TOKEN}
    limits:
      maxConcurrent: 5
    priority: 1

  fallback:
    url: ws://my-playwright-server:4000
    limits:
      maxConcurrent: 10
    priority: 2

browser-gateway serve

アプリから接続します。

// For CDP providers
const browser = await chromium.connectOverCDP('ws://localhost:9500/v1/connect');

// For Playwright run-server providers
const browser = await chromium.connect('ws://localhost:9500/v1/connect');

または、REST API を使用します。WebSocket の管理は不要です。

# Screenshot
curl -X POST http://localhost:9500/v1/screenshot \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}' --output screenshot.png

# Extract content as markdown
curl -X POST http://localhost:9500/v1/content \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}'

これらのエンドポイントで受け付けるのは、パブリックホスト上の http および https URL のみです。ループバック、リンクローカル、プライベート範囲のアドレスは拒否され、ホスト名は解決後に再チェックされます。内部ホストにアクセスするには、gateway.yml の rest.allowedPrivateHosts にホストを追加してください。

ダッシュボードは http://localhost:9500/web にあります。

MCP サーバーとして（AI エージェント向け）

Claude Code または Cursor の設定に追加します。

{
  "mcpServers": {
    "browser-gateway": {
      "command": "npx",
      "args": ["browser-gateway", "mcp"]
    }
  }
}

設定ファイルは不要です。エージェントはゲートウェイのルーティングレイヤーを通じて、navigate、snapshot、screenshot、click、type、evaluate ツールを利用できます。

すべてのオプションについては、MCP ドキュメントをご覧ください。

---

認証

トークンを必須にするには BG_TOKEN を設定します（または .env ファイルに記述します）。

BG_TOKEN=my-secret-token browser-gateway serve

• WebSocket クライアントは、?token= クエリパラメーターでトークンを渡します
• API クライアントは、Authorization: Bearer <token> ヘッダーを使用します
• ダッシュボードにはログインフォームが表示され、安全な HttpOnly Cookie が設定されます
• ヘルスエンドポイント（/health）は常に公開されています

BG_TOKEN を設定していない場合、すべての /v1/* ルートは認証なしで利用できるため、ゲートウェイはすべてのインターフェースではなく 127.0.0.1 にバインドします。他のマシンに公開するには、トークンを設定するか、HOST を明示的に設定してください。BG_ALLOWED_HOSTS を設定すると、トークンが設定されていない場合に /mcp で追加の Host 値を許可できます。

---

CLI

# Proxy server
browser-gateway serve                    # Start the gateway + dashboard
browser-gateway serve --port 8080        # Custom port
browser-gateway serve --config path.yml  # Custom config

# MCP server for AI agents
browser-gateway mcp                      # Auto-detect Chrome, zero config
browser-gateway mcp --headless           # Headless mode (for CI/Docker)
browser-gateway mcp --cdp-endpoint ws:// # Connect to existing browser
browser-gateway mcp --config gateway.yml # Multi-provider with failover

# Utilities
browser-gateway check                    # Test provider connectivity
browser-gateway version                  # Print version
browser-gateway help                     # Show help

---

API

エンドポイント	メソッド	説明
/v1/connect	WebSocket	ブラウザーに接続します（主要機能）
/v1/screenshot	POST	任意の URL のスクリーンショットを撮影します（ドキュメント）
/v1/content	POST	ページのコンテンツを Markdown、テキスト、または HTML として抽出します（ドキュメント）
/v1/scrape	POST	CSS セレクターまたはページ全体の形式を使用してデータを抽出します（ドキュメント）
/v1/status	GET	ゲートウェイのヘルス状態、プロバイダーの状態、プールの状態
/v1/sessions	GET	アクティブなセッション
/v1/providers	GET/POST	プロバイダーの一覧表示または追加
/v1/providers/:id	PUT/DELETE	プロバイダーの更新または削除
/v1/providers/:id/test	POST	プロバイダーの接続をテストします
/v1/config	GET/PUT	設定の読み込みまたは保存
/v1/config/validate	POST	保存せずに YAML を検証します
/mcp	POST	MCP Streamable HTTP エンドポイント
/json/version	GET	CDP ディスカバリー（browser-use、Playwright、Stagehand 向け）
/health	GET	ヘルスチェック

---

Docker

推奨：Docker Compose。付属の docker-compose.yml は、状態を保存する名前付きボリュームと、ホスト上の読み取り専用 gateway.yml をマウントします。

# Drop your gateway.yml next to docker-compose.yml, then:
docker compose up -d

通常の docker run：

docker run -d \
  -p 9500:9500 \
  -v bg_data:/data \
  -v ./gateway.yml:/app/gateway.yml:ro \
  -e PROVIDER_TOKEN=xxx \
  ghcr.io/browser-gateway/server:latest

永続化

ゲートウェイがディスクに書き込むすべてのデータは、単一のディレクトリ BG_DATA_DIR（イメージ内のデフォルトは /data）に保存されます。これを名前付きボリュームまたはバインドマウントとしてマウントすれば、コンテナーの再起動やイメージのアップグレード後もすべての状態が保持されます。現在、次のデータが含まれています。

• profiles/ — 暗号化されたプロファイルの BLOB（プロファイルが有効な場合）

今後のバージョンでは、同じルートの下にサブディレクトリが追加される場合があります（クールダウン状態、セッションスナップショット、キャプチャなど）。BG_DATA_DIR を単一のボリュームとしてマウントすれば、追加の設定変更なしで、すべてのサブシステムのデータを永続化できます。

アップグレード

状態はボリュームに、コードはイメージに保存されます。新しいイメージを取得してコンテナーを再作成すれば、データは失われません。

docker compose pull
docker compose up -d

コンテナーは同じ BG_DATA_DIR と同じ gateway.yml を読み込みます。プロファイルの BLOB にはバージョン情報が付与されており、ゲートウェイは古い形式も透過的に読み込みます。

イメージタグ

タグ	更新時期
:0.3.0（および以降のすべてのバージョン）	リリース後に手動で公開
:latest	常に最新バージョンを参照

イメージはマルチアーキテクチャ（linux/amd64、linux/arm64）に対応し、Sigstore のビルド来歴で署名され、SBOM が同梱されています。GitHub CLI で検証できます。

gh attestation verify oci://ghcr.io/browser-gateway/server:0.3.0 \
  --repo browser-gateway/browser-gateway

---

仕組み

プロファイル／記録／オブザーバビリティのないセッション（デフォルト）では、バイトパイプの高速経路を使用します。

1. クライアントが ws://gateway:9500/v1/connect に接続します
2. ゲートウェイが、ルーティング戦略を使用してプロバイダーを選択します
3. ゲートウェイがプロバイダーへの生の TCP 接続を開きます
4. HTTP アップグレードが転送され、プロバイダーが 101 Switching Protocols を返します
5. 双方向の TCP パイプ：client <-> gateway <-> provider
6. すべての WebSocket メッセージが透過的に転送されます（解析や変更は一切行いません）
7. 切断時：セッションをクリーンアップし、スロットを解放して、メトリクスを更新します
8. すべてのプロバイダーが満杯の場合：スロットが空くまで接続はキューで待機します

プロファイルの挿入、セッション記録、ライブビュー、またはオブザーバビリティを有効にしたセッション（例：?profile=X、?session_record=true、/v1/live）では、代わりに CDP 対応パイプラインを使用します。各セッションに WebSocket を 1 つ使用し、N 個のプラグインが通信を監視します。ルーティングとフェイルオーバーは同じで、待機中はバイト単位で完全にそのまま通過し、プラグインは要求された機能に対してのみ動作します。アーキテクチャとプラグイン作成ガイド： docs/PIPELINE.md。

---

セルフホスト可能なプロバイダー：browserserve

browserserve は、このスタック独自のセルフホスト可能なブラウザーサーバーです。1 つのコンテナーで、分離された Chrome セッションを CDP 経由で提供します。他のプロバイダーと同じように追加できます。

providers:
  browserserve:
    url: ws://your-host:9222
  cloud-provider:
    url: <websocket-url-with-auth>
    priority: 2

ゲートウェイがこのランタイムを管理するため、browserserve プロバイダーは自動検出され、外部プロバイダーでは利用できない次の 2 つの機能が有効になります。

• 容量の自動設定。 maxConcurrent を設定する必要はありません。browserserve がホストのメモリ、スレッド、CPU の制限を測定して安全な上限を通知し、ゲートウェイがそれを採用します。ダッシュボードでは (auto) と表示されます。
• 完全なプロファイル。 すべてのセッションで新しいブラウザーが起動し、保存されたプロファイルには IndexedDB やサービスワーカーを含むブラウザーの状態全体が保持されます。他のプロバイダーでは、Cookie とサイトストレージが保存されます。

よくある構成は、自前のハードウェア上で browserserve をプライマリプロバイダーとして使用し、フェイルオーバー用に優先度の低いクラウドプロバイダーを設定する形です。

---

対応ツール

browser-gateway は既存のブラウザーツールと互換性があります。ゲートウェイ URL を渡すだけで、/json/version 経由で自動的に解決します。

AI エージェントフレームワーク：

# browser-use (Python) — HTTP URL auto-resolves
BrowserSession(cdp_url="http://localhost:9500")

// Stagehand (TypeScript)
new Stagehand({ env: "LOCAL", localBrowserLaunchOptions: { cdpUrl: "http://localhost:9500" } })

Playwright MCP（Playwright の全 70 ツールでゲートウェイルーティングを利用）：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--cdp-endpoint", "http://localhost:9500"]
    }
  }
}

Puppeteer / Playwright：

// Playwright — HTTP or WebSocket
const browser = await chromium.connectOverCDP("http://localhost:9500");

// Puppeteer — WebSocket
const browser = await puppeteer.connect({ browserWSEndpoint: "ws://localhost:9500/v1/connect" });

---

ドキュメント

ドキュメントの全文は docs.browsergateway.com にあります。

• はじめに
• 設定リファレンス
• 対応プロバイダー
• プロファイル — 永続的なブラウザー状態
• セッションリプレイ
• セッションのライフサイクル
• REST API
• AI エージェント向け MCP サーバー
• コンピューター操作（Claude と Gemini）
• CLI リファレンス
• Web ダッシュボード
• フェイルオーバーの仕組み
• 負荷分散戦略
• リクエストキュー
• Webhooks
• Docker によるデプロイ
• インテグレーション — Playwright、Puppeteer、browser-use、Stagehand、Playwright MCP

---

コントリビューション

コントリビューションを歓迎します。ガイドラインについては CONTRIBUTING.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。

リンク

• browsergateway.com
• docs.browsergateway.com
• GitHub
• npm

お問い合わせ

ご質問、セキュリティに関する報告、提携に関するお問い合わせは、[email protected] までご連絡ください。