← Sandbox SDK / sandbox / configuration

Režimy transportu

Nakonfigurujte, jak Sandbox SDK komunikuje s kontejnery pomocí přenosových režimů.

Sandbox SDK podporuje tři přenosové režimy pro komunikaci mezi Durable Object a kontejnerem:

• HTTP transport (výchozí) - Každá operace SDK odešle samostatný HTTP požadavek do kontejneru.
• NOVÉ: RPC transport - Všechny operace SDK jsou multiplexovány přes jedno trvalé WebSocket spojení. V budoucnu nahradí HTTP jako výchozí transport. Dostupné od verze 0.9.1.
• Zastaralé: transport WebSocket - Všechny operace SDK jsou multiplexovány přes jedno trvalé WebSocket spojení. Nahrazeno transportem RPC, který používá vylepšený protokol.

Použijte RPC transport, pokud váš Worker nebo Durable Object provádí mnoho operací SDK na jeden požadavek. Zabráníte tak dosažení limity subrequestů.

Cloudflare Workers mají limity subrequestů, které platí při volání externích služeb, včetně volání API kontejneru:

• Workers Free: 50 subrequestů na požadavek
• Workers Paid: 1,000 subrequestů na požadavek

S HTTP transportem (výchozí) každá operace SDK (exec(), readFile(), writeFile(), atd.) spotřebuje jeden subrequest. Aplikace, které v rámci jednoho požadavku provádějí mnoho operací se sandboxem, mohou na tyto limity narazit.

RPC transport naváže jedno trvalé spojení s kontejnerem a multiplexuje přes něj všechny operace SDK. WebSocket upgrade se počítá jako jeden dílčí požadavek bez ohledu na to, kolik operací poté provedete.

Příklad s HTTP transportem (4 dílčí požadavky):

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");

Stejný kód s přenosem RPC (1 subrequest):

// 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 transport zároveň odstraňuje Omezení 32 MiB který má HTTP transport. Předejte ReadableStream instanci na writeFile() metoda.

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

Nastavte SANDBOX_TRANSPORT proměnná prostředí v konfiguraci vašeho Workeru. SDK ji načítá z vazeb prostředí Workeru (nikoli zevnitř kontejneru).

HTTP transport je výchozí a nevyžaduje žádnou další konfiguraci.

RPC transport povolíte přidáním SANDBOX_TRANSPORT do svého Workeru vars:

{
	"name": "my-sandbox-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"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-08-28"

[vars]
SANDBOX_TRANSPORT = "rpc"

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

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

Není potřeba měnit kód aplikace. SDK pro všechny operace automaticky použije nakonfigurovaný transport.

HTTP transport:

• Vytvoří nový HTTP požadavek pro každou operaci SDK
• Žádné trvalé spojení
• Každý požadavek je nezávislý a bezstavový

RPC transport:

• Při první operaci SDK naváže WebSocket spojení
• Udržuje trvalé připojení pro všechny následující operace
• Připojení se ukončí, jakmile sandbox přejde do režimu spánku nebo je vyřazen
• Automaticky se znovu připojí, pokud spojení vypadne

Všechny transporty podporují streamované operace (například exec() s výstupem v reálném čase):

• HTTP transport - Používá Server-Sent Events (SSE)
• Transport RPC - Používá streamované zprávy přes WebSocket

Váš kód zůstává stejný bez ohledu na režim přenosu.

Všechny transporty poskytují stejné chování při ošetřování chyb. SDK automaticky opakuje pokusy u přechodných chyb (například odpovědí 503) s exponenciálně rostoucí prodlevou mezi pokusy (exponential backoff).

Chování specifické pro WebSocket:

• Chyby připojení spustí automatické opětovné připojení
• SDK transparentně řeší odpojení WebSocket
• Probíhající operace se při opětovném připojení neztratí

Očekáváme, že RPC transport v budoucí verzi nahradí výchozí HTTP transport. Nová funkcionalita může podporovat pouze RPC transport. Přechodem na něj již nyní se v budoucnu vyhnete migracím.

Přepínání mezi přenosovými protokoly nevyžaduje žádné změny kódu.

Přidejte SANDBOX_TRANSPORT do vašeho wrangler.jsonc:

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

[vars]
SANDBOX_TRANSPORT = "rpc"

Poté nasaďte:

npx wrangler deploy

Odeberte SANDBOX_TRANSPORT proměnnou (nebo ji nastavte na "http"):

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

vars = { }

Nastavte SANDBOX_TRANSPORT proměnnou na "rpc":

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

[vars]
SANDBOX_TRANSPORT = "rpc"

• Konfigurace Wrangleru - Kompletní konfigurace Workeru
• Proměnné prostředí - Předávání konfigurace sandboxům
• Limity subrequestů Workers - Pochopení limitů dílčích požadavků
• Architektura - Jak spolu komunikují komponenty Sandbox SDK