HTTP API リファレンス

このページは、安定版テンプレート上の sandbox bridge が公開するすべてのルートを記載します。

/v1/sandbox/* と /v1/openapi.* 配下のすべてのルートには Bearer トークンが必要です。

Authorization: Bearer <SANDBOX_API_KEY>

SANDBOX_API_KEY が未設定のときは、ローカル開発の便宜のため認証をスキップします。本番へデプロイする前に、必ずシークレットを設定してください。

bridge は自身の API ドキュメントを提供します。

両方のルートは、Bearer ヘッダーまたは ?token= クエリパラメーターで認証できます。

ローカルで npm run dev を実行しているときは、ブラウザーで http://localhost:8787/v1/openapi を開き、各エンドポイントを対話的に確認できます。

/exec エンドポイントは次の JSON ボディを受け付けます。

{
  "argv": ["sh", "-lc", "echo hello"],
  "timeout_ms": 10000,
  "cwd": "/workspace"
}

argv 配列の各要素は、シェルコマンドに結合する前に ANSI-C の $'...' クォートでエスケープされます。安全な文字（A-Za-z0-9@%+=:,./-）だけを含むトークンはそのまま渡します。それ以外のトークンは $'...' で囲み、バックスラッシュ、シングルクォート、改行、キャリッジリターン、タブをエスケープします。これによりシェルインジェクションを防ぎつつ、スペース、引用符、特殊文字を含む引数を保てます。

レスポンスは text/event-stream で、次のイベント種別があります。

ファイルパスは URL の /file/ のあとにエンコードします。すべてのパスは /workspace 内に解決される必要があります。パストラバーサル（例: ../../etc/passwd）は拒否されます。

/persist エンドポイントは、オプションの excludes クエリパラメーターを受け付けます。アーカイブから除外する相対パスをカンマ区切りで指定します。

/hydrate エンドポイントは、最大 32 MiB の生 tar ペイロードを受け付けます。

/mount エンドポイントは JSON ボディを受け付けます。次の 2 つの流れに対応しています。

endpoint を省略し、bucket に Worker の R2 バインディング名を渡します。

{
  "bucket": "MY_BUCKET",
  "mountPath": "/mnt/data",
  "options": {
    "readOnly": false,
    "prefix": "/subdir"
  }
}

options.endpoint を省略したとき、bucket は Worker の R2 バインディング名を意味します。

明示的な S3 互換エンドポイントへマウントする場合は、endpoint を含め、必要に応じて credentials も指定します。

{
  "bucket": "my-r2-bucket",
  "mountPath": "/mnt/data",
  "options": {
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
    "readOnly": false,
    "prefix": "/subdir",
    "credentials": {
      "accessKeyId": "...",
      "secretAccessKey": "..."
    }
  }
}

endpoint を指定したとき、bucket はリモートのバケット名を意味します。このモードでは認証情報は任意です。省略すると、bridge は Worker のシークレット（R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY または AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY）から自動検出します。

セッションは、サンドボックス内で作業ディレクトリ、環境変数、コマンド実行状態を分離します。/exec、/file/*、/pty リクエストに Session-Id ヘッダーを付けると、そのセッションにスコープします。

Session-Id ヘッダーがない場合、リクエストはサンドボックスの暗黙的な実行モードを使います。デフォルトではデフォルトセッションです。ただし enableDefaultSession: false を設定した SDK では、これらの暗黙的な操作はセッションなしで実行されます。

クエリパラメーター:

WebSocket は、ターミナル I/O にバイナリフレーム、制御メッセージに JSON テキストフレームを使います。

ウォームプールはサンドボックスコンテナを事前起動し、新しいセッションをすぐ起動できるようにします。wrangler.jsonc の環境変数で設定します。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "vars": {
    "WARM_POOL_TARGET": "3",
    "WARM_POOL_REFRESH_INTERVAL": "10000"
  }
}

[vars]
WARM_POOL_TARGET = "3"           # Number of idle containers to keep warm (0 = disabled)
WARM_POOL_REFRESH_INTERVAL = "10000"  # Health-check interval in milliseconds

デプロイ後、cron トリガー（* * * * *）がプールを自動で事前起動します。WARM_POOL_TARGET を "0"（デフォルト）にするとプールを無効にし、想定外の課金を避けられます。

• Bridge の概要 — bridge の役割、デプロイ、利用例。
• Sandbox API リファレンス — Sandbox SDK のメソッド一覧。
• GitHub 上の Bridge ソース ↗ — Worker、Dockerfile、OpenAPI スキーマ。