トランスポートモード

トランスポートモードを使い、Sandbox SDK がコンテナと通信する方法を設定します。

Sandbox SDK は、Durable Object とコンテナの通信に 3 つのトランスポートモードをサポートします。

• HTTP トランスポート（デフォルト） - 各 SDK 操作がコンテナへ個別の HTTP リクエストを送ります。
• 新機能: RPC トランスポート - すべての SDK 操作を、1 本の永続 WebSocket 接続上で多重化します。将来、デフォルトのトランスポートとして HTTP に置き換わる予定です。0.9.1 以降で利用できます。
• 非推奨: WebSocket トランスポート - すべての SDK 操作を、1 本の永続 WebSocket 上で多重化します。改善されたプロトコルを使う RPC トランスポートに置き換えられました。

Worker または Durable Object が、1 リクエストあたり多くの SDK 操作を行う場合は RPC トランスポートを使います。サブリクエスト制限 に達するのを避けられます。

Cloudflare Workers には、コンテナ API 呼び出しを含む外部サービスへのリクエストに適用されるサブリクエスト制限があります。

• Workers Free: リクエストあたり 50 サブリクエスト
• Workers Paid: リクエストあたり 1,000 サブリクエスト

HTTP トランスポート（デフォルト）では、各 SDK 操作（exec()、readFile()、writeFile() など）がサブリクエストを 1 つ消費します。1 リクエスト内で多くのサンドボックス操作を行うアプリケーションは、この制限に達することがあります。

RPC トランスポートはコンテナへの永続接続を 1 本確立し、その上ですべての SDK 操作を多重化します。WebSocket のアップグレードは、その後に何回操作しても 1 サブリクエスト としてカウントされます。

HTTP トランスポートの例（4 サブリクエスト）:

await sandbox.exec("python setup.py");
await sandbox.writeFile("/app/config.json", config);
await sandbox.exec("python process.py");
const result = await sandbox.readFile("/app/output.txt");

同じコードを RPC トランスポートで実行した場合（1 サブリクエスト）:

// Identical code - transport is configured via environment variable
await sandbox.exec("python setup.py");
await sandbox.writeFile("/app/config.json", config);
await sandbox.exec("python process.py");
const result = await sandbox.readFile("/app/output.txt");

RPC トランスポートは、HTTP トランスポートにある 32 MiB の制限 も取り除きます。writeFile() メソッドに ReadableStream インスタンスを渡せます。

const req = await fetch("https://example.com/archive.tar.gz");
await sandbox.writeFile("/archive.tar.gz", req.body);

Worker の設定で SANDBOX_TRANSPORT 環境変数を設定します。SDK は Worker の環境バインディングからこの値を読みます（コンテナ内部からではありません）。

HTTP トランスポートがデフォルトであり、追加の設定は不要です。

Worker の vars に SANDBOX_TRANSPORT を追加して、RPC トランスポートを有効にします。

{
	"name": "my-sandbox-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
}

name = "my-sandbox-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-09-20"

[vars]
SANDBOX_TRANSPORT = "rpc"

[[containers]]
class_name = "Sandbox"
image = "./Dockerfile"

[[durable_objects.bindings]]
class_name = "Sandbox"
name = "Sandbox"

アプリケーションコードの変更は不要です。SDK は設定したトランスポートを、すべての操作に自動で使います。

HTTP トランスポート:

• 各 SDK 操作ごとに新しい HTTP リクエストを作成します
• 永続接続はありません
• 各リクエストは独立し、ステートレスです

RPC トランスポート:

• 最初の SDK 操作で WebSocket 接続を確立します
• 以降の操作すべてで永続接続を維持します
• サンドボックスがスリープまたは退避されると接続は閉じます
• 接続が切れた場合は自動で再接続します

すべてのトランスポートがストリーミング操作（リアルタイム出力付きの exec() など）に対応します。

• HTTP トランスポート - Server-Sent Events（SSE）を使います
• RPC トランスポート - WebSocket のストリーミングメッセージを使います

トランスポートモードに関係なく、コードは同じです。

すべてのトランスポートで、エラー処理の動作は同じです。SDK は一時的なエラー（503 レスポンスなど）に対して、指数バックオフで自動リトライします。

WebSocket 固有の動作:

• 接続失敗時は自動再接続します
• SDK は WebSocket の切断を透過的に扱います
• 再接続中に進行中の操作は失われません

将来のリリースで、RPC トランスポートがデフォルトの HTTP トランスポートに置き換わる見込みです。新しい機能は RPC トランスポートだけをサポートすることがあります。今のうちに切り替えておくと、将来の移行を避けられます。

トランスポートの切り替えに、コード変更は不要です。

wrangler.jsonc に SANDBOX_TRANSPORT を追加します。

{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}

[vars]
SANDBOX_TRANSPORT = "rpc"

次にデプロイします。

npx wrangler deploy

SANDBOX_TRANSPORT 変数を削除します（または "http" に設定します）。

{
	"vars": {
		// Remove SANDBOX_TRANSPORT or set to "http"
	},
}

vars = { }

SANDBOX_TRANSPORT 変数を "rpc" に設定します。

{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}

[vars]
SANDBOX_TRANSPORT = "rpc"

• Wrangler の設定 - Worker 設定の全体
• 環境変数 - サンドボックスへの設定の渡し方
• Workers のサブリクエスト制限 - サブリクエスト制限の説明
• アーキテクチャ - Sandbox SDK コンポーネント間の通信