← Sandbox SDK / sandbox

1.0 preview

Sandbox SDK 1.0 je další hlavní verze SDK. Nyní je k dispozici jako preview na npm @next tag. Aktuální stabilní balíček zůstává publikovaný pro stávající aplikace.

Sandbox stále spouští izolovanou práci na Cloudflare Containers. 1.0 preview je tenčí SDK na tomto základu: jeden handle procesu pro krátké i dlouhotrvající úlohy, žádný stav příkazů vázaný na relaci, žádný výběr transportu, terminály jako plnohodnotné PTY a interpret kódu jako volitelné rozšíření.

Doporučujeme, abyste nové projekty začít s @cloudflare/sandbox@next a postupujte podle této části. Existující aplikace byste měli migrovat, jakmile to půjde, abyste byli připraveni na chvíli, kdy se 1.0 stane stabilním vydáním. Postupujte podle Migrace.

Hlavní Dokumentace k sandboxu stále popisuje aktuální stabilní balíček. Použijte toto sekci s náhledovými API a postupem migrace.

npm i @cloudflare/sandbox@next

Nasaďte balíček Workeru a image kontejneru sandboxu ze stejný preview řádek. Nekombinujte preview balíček Workeru se stabilním image kontejneru (ani naopak). Pro pokračující nasazení najdete více informací v Nasazení aplikace Sandbox. Pro přechod s nekompatibilními změnami viz Migrace.

Stabilnímu balíčku postupně přibylo několik způsobů spouštění příkazů (exec, startProcess, execStream), volitelný stav relace napříč spuštěními a volitelné transporty mezi Durable Object a kontejnerem. Toto rozhraní fungovalo, ale duplikovalo myšlenky a skrývalo, jak se sandboxy na kontejnerech ve skutečnosti chovají.

Náhled to zjednodušuje na menší kontrakt:

Postupy: Migrace. Mentální model: Provádění procesů a Životní cyklus sandboxu.

Stabilní: sandbox.exec(string) se vyřeší, když příkaz skončí s bufferovaným výstupem. Dlouhotrvající služby a streamování používají samostatná API (startProcess, execStream).

Náhled: sandbox.exec() přijímá argv a vyřeší se, když proces spouští se. Stejný handle pokrývá krátké příkazy i dlouhotrvající služby.

// Current stable package
const result = await sandbox.exec("npm test");
console.log(result.stdout, result.exitCode);

// 1.0 preview
const process = await sandbox.exec(["npm", "test"]);
const result = await process.output({ encoding: "utf8" });
console.log(result.stdout, result.exitCode);

// Current stable package
const result = await sandbox.exec("npm test");
console.log(result.stdout, result.exitCode);

// 1.0 preview
const process = await sandbox.exec(["npm", "test"]);
const result = await process.output({ encoding: "utf8" });
console.log(result.stdout, result.exitCode);

Funkce shellu jako roury a && potřebují explicitní shell, například ['/bin/bash', '-lc', 'cd app && npm test']. Předejte cwd a env při každém exec() když je proces potřebuje. Podrobnosti: Provádění procesů, Processes API.

Stabilní: výchozí relace může zachovat pracovní adresář a proměnné prostředí napříč exec() volání. Aplikace mohou také vytvářet pojmenované relace pomocí createSession().

Náhled: žádné spouštění relací v SDK. Každý exec() je nezávislý. Předejte cwd a env při každém spuštění, nebo vložte vícekrokovou shellovou syntaxi do jednoho explicitního shell argv. Izolujte koncové uživatele pomocí samostatné sandboxy, nikoli relace uvnitř jednoho sandboxu. Model prostředí: Proměnné prostředí.

Stabilní: shelly v prohlížeči často používají sandbox.terminal(request) s pomocnými funkcemi relace a xterm sessionId.

Náhled: terminály jsou prostředky PTY: createTerminal, getTerminal, listTerminals, a terminal.connect(request). Pomocník xterm používá terminalId. Viz Terminály.

Stabilní: metody interpretu se nacházejí na Sandbox.

Náhled: připojte interpret k vaší podtřídě a poté zavolejte sandbox.interpreter.*. Viz Code interpreter.

Stabilní: aplikace si mohou zvolit HTTP, WebSocket nebo RPC pro komunikaci mezi Durable Object a kontejnerem.

Náhled: SDK vždy používá RPC. Odeberte SANDBOX_TRANSPORT, transport možnost na getSandbox(), a setTransport(). Není potřeba žádné náhradní nastavení.

Toto je ne nový kontejnerový produkt. Sandbox stále adresujete pomocí stabilní ID sandboxu:

const sandbox = getSandbox(env.Sandbox, "user-123");

const sandbox = getSandbox(env.Sandbox, "user-123");

Tento sandbox běží v kontejner. ID je stabilní, instance containeru za ním ale nemusí být pokaždé stejná. Procesy a terminály, které spustíte, existují pouze v aktuální kontejner. Jakmile se tento kontejner zastaví nebo je nahrazen, dané procesy a terminály zaniknou: staré handly selžou uzavřením spojení, místo aby se tiše připojily k novému kontejneru se stejným sandbox ID.

Zastavení a nahrazení kontejneru je na stabilní větvi už realitou. Náhled zajišťuje, že rozhraní API pro procesy a terminály tuto životnost věrně odrážejí. Úplný model: Životní cyklus sandboxu. Podrobnosti o procesu: Jak dlouho proces žije. Obnova: Chyby a zotavení.

Tyto zůstávají k dispozici. Pro signatury použijte hlavní dokumentaci Sandboxu a ignorujte možnosti relace nebo transportu, pokud je tyto stránky ještě zmiňují:

• Soubory a sledování souborů
• Úložiště a zálohy
• Porty a tunely
• Možnosti životního cyklu a možnosti sandboxu (kromě odebraných polí session/transport)
• Odchozí provoz (vkládání přihlašovacích údajů a zásady odchozího provozu)

Pro prostředí procesu na @next, použijte Proměnné prostředí v této části.

Nainstalujte Cloudflare Skills ↗ pro svého agenta (Nastavení agenta). Použijte sandbox-next pro práci na @next (doporučeno pro nové projekty). Existující aplikace používající aktuální stabilní balíček by měly použít sandbox-stable dokud nebudete připraveni na přesun, a poté sandbox-migrate-to-next. Úklidem zastaralých API při zachování stabilní verze se zabývá Průvodce ukončením podpory 2026 a sandbox-stable.

Pokud zůstáváte u aktuálního stabilního balíčku, použijte hlavní dokumentaci:

• Začínáme
• Příkazy
• Relace
• Migrace kvůli ukončení podpory 2026