← Sandbox SDK / sandbox / 1-0-preview

Migrace

Než začnete

Pracujte na větvi nebo na stagingovém nasazení. Dokončete kroky migrace kódu z tohoto návodu a produkci pak přepněte jedním nasazením.
Počítejte s krátkým výpadkem při přepnutí. Když nový image nahradí ten starý, běžící procesy, terminály a další práce v kontejneru se zastaví.
Zjistěte místa volání ve Workeru:
- Příkazy: exec, execStream, startProcess, řetězcové signály ukončení, standardní vstup procesu
- Relace a transport: createSession, enableDefaultSession, SANDBOX_TRANSPORT, setTransport
- Terminály: sandbox.terminal, relace terminal(), xterm sessionId
- Interpreter: createCodeContext / runCode na čistém Sandbox
- Git: gitCheckout

Pokud stále nejprve potřebujete stable-line cleanup (RPC transport, exposePort, pomocníky proudu), dokončete Migrace kvůli ukončení podpory 2026, pak se vraťte sem.

Co změníte

Stabilní rozhraní	Akce náhledu
`SANDBOX_TRANSPORT`, `transport` na `getSandbox()`, `setTransport()`	Odebráno. Náhled nyní používá RPC automaticky, nastavení transportu není potřeba.
`await sandbox.exec(string)` → bufferovaný výsledek	`await sandbox.exec(argv)` poté `await process.output(...)`.
`execStream`, `startProcess`, process log helpery	Popisovač procesu: `logs`, `kill`, `waitFor*`.
Výchozí relace / `enableDefaultSession`	Odstraněno. Každý `exec` je nezávislý.
`createSession` / `ExecutionSession`	Odstraněno z hlavního veřejného rozhraní. Předejte `cwd`/`env` na `exec`, nebo jeden shellový argv skript.
Metody Interpreteru na `Sandbox`	Stejné názvy metod na `sandbox.interpreter` po `withInterpreter`. `runCode` vrátí čistá `ExecutionResult`. Viz Code interpreter.
Signály ukončení procesu jako řetězce	Číselné signály na `process.kill`.
`waitForPort` výchozí režim	Výchozí hodnota náhledu je `tcp`. Předejte `mode: "http"` pro HTTP kontroly.
Proces / datový proud stdin	Na handle není k dispozici žádný stdin procesu. Neinteraktivní: argv/`cwd`/`env`. Interaktivní PTY: terminály.
`sandbox.terminal(request)` / session `terminal()`	`createTerminal`, poté `terminal.connect(request)`.
xterm `sessionId`	`terminalId` (a volitelně `cursor`).
`sandbox.gitCheckout(...)`	Odebráno. Spusťte `git` s argv `exec`, například `['git', 'clone', '--', url, dir]`, poté `output()` / waits podle potřeby.

Soubory, připojení, zálohy, porty, tunely, proxyToSandbox, a většina možností životního cyklu zůstává dostupná. Pro tyto signatury použijte hlavní dokumentaci Sandboxu. Tam, kde stabilní stránka stále popisuje relace, výběr transportu, řetězcové exec helpery, nebo sandbox.terminal, postupujte místo toho podle této náhledové části.

Nainstalujte balíček náhledu a image

npm i @cloudflare/sandbox@next

Zkontrolujte, že lockfile řeší @cloudflare/sandbox na náhledový build. Nasměrujte svůj Dockerfile na odpovídající náhledový image, například cloudflare/sandbox:next (nebo -python / jiná varianta, kterou používáte).

Nekombinujte preview balíček Worker se stabilním obrazem kontejneru, ani naopak. Obě strany musí pocházet ze stejné @next řádek.

Odebrání volby transportu

Odstranit SANDBOX_TRANSPORT, transport možnost na getSandbox(), SandboxTransport typy a sandbox.setTransport(). Není potřeba žádné náhradní nastavení.

Migrace spouštění příkazů

Bufferované příkazy

Stabilní:

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

Náhled:

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

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

Pravidla:

await sandbox.exec(...) znamená spuštění bylo úspěšné, nikoli příkaz dokončen.
Pokud spouštíte jediný binární soubor, upřednostněte argv bez shellu: ['npm', 'test'] hodnotou cwd nastaveno.
output() má výchozí hodnotu bajt streamuje (Uint8Array). Předejte { encoding: "utf8" } pro řetězce.
Neexistuje žádné sandbox.run() pomocník pro kompatibilitu v aktuální preview verzi.

Procesy na pozadí a streamování

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

// Default readiness mode is TCP. Use mode: "http" when you need an HTTP check.
await server.waitForPort(3000, { timeout: 60_000 });
// await server.waitForPort(3000, { mode: "http", path: "/health", timeout: 60_000 });

const stream = await server.logs({ follow: true, replay: true });
// consume stream...

await server.kill(); // numeric signal; default 15

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

// Default readiness mode is TCP. Use mode: "http" when you need an HTTP check.
await server.waitForPort(3000, { timeout: 60_000 });
// await server.waitForPort(3000, { mode: "http", path: "/health", timeout: 60_000 });

const stream = await server.logs({ follow: true, replay: true });
// consume stream...

await server.kill(); // numeric signal; default 15

Podrobnosti popisovače procesu (čekání, události protokolu, kill, bez stdin): Processes API.

Napříč požadavky Worker udržujte server.id a obnovte pomocí getProcess(id) pouze dokud tento proces může v aktuálním kontejneru stále běžet. Pokud se kontejner zastavil, getProcess může vrátit null. Pokud stále držíte handle z předchozího kontejneru, očekávejte chybu neplatného handlu. V obou případech spusťte nový exec z práce, kterou ještě musíte spustit. Viz Jak dlouho proces žije.

Pracovní adresář a prostředí

Stable	Náhled
`exec("cd /app"); exec("npm test");`	`exec(['/bin/bash', '-lc', 'cd /app && npm test'])` nebo `exec(['npm', 'test'], { cwd: '/app' })`
Exportované proměnné ve výchozí relaci	`setEnvVars` a/nebo `env` při každém `exec`
`createSession({ env })`	`setEnvVars` a/nebo `env` při každém `exec` / `createTerminal`

Podrobnosti: Proměnné prostředí.

Nevkládejte živé klíče API ani dlouhodobě platné přístupové údaje poskytovatele do setEnvVars nebo spusťte env. Uchovávejte tajné klíče ve Workeru a vkládejte je pomocí odchozí provoz handlery, když proces musí volat externí API.

Časové limity a zrušení

Cíl	API
Omezte životnost procesu	`exec(argv, { timeout })` : může skončit s `timedOut: true`
Omezte dobu čekání	Možnosti nebo `AbortSignal` na `output` / waits / `logs` : provádí ne ukončí proces

API pro ukončení relace

Odebrat createSession, getSession, deleteSession, a sessionId voleb u základních volání.

Izolace uživatelů zůstává jeden sandbox na uživatele (nebo podle hranice důvěryhodnosti), nikoli relace uvnitř jednoho sandboxu.

Připojte interpret

Viz Code interpreter. Minimum:

import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
import { withInterpreter } from "@cloudflare/sandbox/interpreter";

export class Sandbox extends BaseSandbox {
	interpreter = withInterpreter(this);
}

import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
import { withInterpreter } from "@cloudflare/sandbox/interpreter";

export class Sandbox extends BaseSandbox<Env> {
	interpreter = withInterpreter(this);
}

Použijte -python image varianta při spouštění Pythonu. Worker balíček a image kontejneru udržujte na stejné @next řádek.

Git

sandbox.gitCheckout je odstraněn. Klonujte nebo fetchujte pomocí argv exec, například:

const clone = await sandbox.exec(
	["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
	{ cwd: "/workspace" },
);
const result = await clone.output({ encoding: "utf8" });

const clone = await sandbox.exec(
	["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
	{ cwd: "/workspace" },
);
const result = await clone.output({ encoding: "utf8" });

Terminály

Nahraďte stable sandbox.terminal(request) (a s platností pro danou relaci terminal()) pomocí API prostředku náhledového terminálu:

const terminal = await sandbox.createTerminal({ command: ['bash'], ... })
Uložte terminal.id s ID sandboxu.
Při upgradu na WebSocket: getTerminal(id) poté terminal.connect(request, { cursor?, cols?, rows? }).
V prohlížeči @cloudflare/sandbox/xterm používá terminalId.

Podrobnosti: Terminály, Terminals API.

Samostatně nasazený bridge

Tato příručka se týká aplikací Worker SDK na @next.

Samostatně nasazený Sandbox bridge zůstává na stabilní vývojové větvi. Udržujte balíček Workeru, image kontejneru i HTTP klienty na odpovídajících stabilních verzích. Nekombinujte přechodové nasazení s @cloudflare/sandbox@next.

Životní cyklus ve verzi preview

Na @next, ID sandboxu zůstává stabilní, ale kontejner za ním lze nahradit. Procesy a terminály existují pouze v rámci aktuálního kontejneru. Po nahrazení staré handly selžou a práci musíte začít znovu.

Po nečinnosti, restartech a tomto přechodu v rámci migrace je to normální. Úplný model: Životní cyklus sandboxu a Jak dlouho proces žije. Vzory obnovy: Chyby a zotavení. Katalog: API chyb.

Když migrujete dlouhotrvající práci:

Nepokládejte uložené process.id nebo terminal.id jako dostatečné pro obnovení po libovolném zpoždění nebo po nasazení.
Uložte příkaz, cwd, env, a libovolný checkpoint aplikace, který potřebujete znovu spustit.
Při pozdějším požadavku zavolejte getProcess(id) / getTerminal(id) pouze pokud tento prostředek může v aktuálním kontejneru stále běžet. Pokud dostanete null nebo chybu zastaralého handle, začněte znovu od uložené práce.

Alespoň tyto chyby ošetřete následujícím způsobem:

Chyba	Co dělat
`ContainerUnavailableError`	Kontejner nezahájil práci, počkejte (`retryAfterMs` je-li nastavena), a poté zkuste práci znovu
`StaleProcessHandleError` / `StaleTerminalHandleError`	Předchozí kontejner: obnovení z uloženého stavu práce
`OperationInterruptedError`	Práce už možná začala, přečtěte si `reason` / `retryable`; před opakováním zkontrolujte stav
`RPCTransportError`	Ztráta spojení během volání: pozdější volání může fungovat, toto volání již možná proběhlo
`ProcessWaitTimeoutError` / `ProcessAbortedError`	Skončilo pouze čekání: proces může stále běžet
`RuntimeControlProtocolError` nebo nepoužitelný image po nasazení	Balíček Workeru a image kontejneru se musí shodovat na stejné `@next` řádek; nepovažujte to za pomalý start

getProcess / getTerminal / list* nespouštějí kontejner. Vrací null nebo [] když žádný neběží (nejde o výjimku).

Proveďte přechod

Nejprve v tomto průvodci dokončete kroky migrace kódu ve větvi. Přechod do produkce pak představuje jediné nasazení balíčku preview Workeru a odpovídajícího image kontejneru.

Stabilní Sandbox a @next používají odlišné řídicí protokoly. Kombinace obou verzí nefunguje v žádném směru: nový kód Workeru se starým obrazem kontejneru selže a starý kód Workeru s novým obrazem kontejneru selže rovněž.

Při běžném wrangler deploy, kód Workeru se aktivuje okamžitě, zatímco instance kontejnerů se mohou aktualizovat postupně. Vzniká tak okno, kdy nový kód Workeru může komunikovat se starými kontejnery. Pro tuto migraci nasaďte kontejnery v jednom kroku:

npx wrangler deploy --containers-rollout=immediate

--containers-rollout=immediate nepřepisuje rollout_active_grace_period. Ponechte toto nastavení na výchozí hodnotě 0 pro přechod (nebo ji nastavte na 0 pokud jste ji dříve zvýšili). Nenulová ochranná lhůta udržuje staré kontejnery déle aktivní, zatímco nový Worker už běží.

Před nasazením do produkce:

Práci, kterou potřebujete zachovat i během přechodu, dokončete nebo zastavte.
Nasaďte pomocí příkazu pro okamžité zavedení kontejneru z předchozí části.
Počkejte, až nový image kontejneru začne obsluhovat provoz.
ID procesů a terminálů z doby před nasazením považujte za neplatná. Danou práci spusťte znovu a použijte nová ID.
Spusťte kontroly v Ověřit.

Pro běžná nasazení po migraci se podívejte na Nasazení aplikace Sandbox. Možnosti postupného nasazení najdete v Rollouty.

Ověřit

Zkontrolujte, že lockfile i Dockerfile mají stejnou @next řádek a poté nasaďte pomocí --containers-rollout=immediate.
Spuštění jednoho argv exec a output({ encoding: "utf8" }).
Spuštění jednoho dlouhotrvajícího procesu pomocí waitForPort nebo logs.
Pokud aplikace používá terminál v prohlížeči, vytvořte, připojte a obnovte pomocí getTerminal zatímco ho kontejner ještě má.
Interpret používejte pouze tehdy, pokud vaše aplikace dané rozšíření využívá (Python vyžaduje -python).
Zkontrolujte, že zpracování chyb rozlišuje mezi nedostupností, přerušením/RPC, neplatným handle a lokálním vypršením čekání, Chyby a zotavení.
Zkontrolujte, že tajné klíče nejsou uloženy v prostředí sandboxu. Tam, kde je to potřeba, použijte outbound handlery.
Znovu prohledejte pomocí grep odstraněná API (transport, sessions, execStream, startProcess, sandbox.terminal, gitCheckout, xterm sessionId).

Kódovací agenti

Nainstalujte Cloudflare Skills ↗ pro svého agenta (Nastavení agenta). sandbox-migrate-to-next dovednost provede tuto migraci. U nových aplikací na @next, použijte sandbox-next. Pro každodenní práci s aktuálním stabilním balíčkem použijte sandbox-stable. Úklid zastaralých API při zachování stabilní verze najdete v Průvodce ukončením podpory 2026 (a sandbox-stable) před tímto návodem nebo místo něj.