INTEGRITY Dokumentace

← Sandbox SDK / sandbox / 1-0-preview

Řešení potíží

Použijte tuto mapu příznaků a jejich řešení. Pro hlubší nápravu viz Chyby a zotavení. Chování životního cyklu najdete v Životní cyklus sandboxu.

Nasazení a image

Příznak Co zkontrolovat
RuntimeControlProtocolError, selhání řízení nebo protokolu po nasazení Balíček Workeru a image kontejneru jsou z různých vývojových větví. Použijte stejnou @next / cloudflare/sandbox:next (nebo stejnou přesnou verzi prerelease) dvojici.
Kontejner nikdy není připraven, nebo se opakovaně zobrazuje ContainerUnavailableError Studený start nebo nedostatek kapacity. Zpomalte pomocí retryAfterMs je-li nastavena, a poté zopakujte práce. Viz Chyby a zotavení.
Funguje v wrangler dev, selže pouze v produkci Limity platné pouze pro produkci a studený start. Balíček a image musí přesto zůstat sladěné.

Procesy

Příznak Co zkontrolovat
await exec „skončil“, ale příkaz ne exec se vyřeší při spuštění. Použijte output(), waitForExit(), nebo exitCode.
Žádný stdout jako řetězec output() je ve výchozím nastavení bytes. Předejte { encoding: "utf8" }.
getProcess je null / list je [] Neběží žádný kontejner nebo je ID neznámé v aktuální kontejner. Vyhledání sandboxu ho neprobouzí. V případě potřeby ho znovu spusťte z uloženého stavu úlohy.
StaleProcessHandleError Handle pocházel z předchozího kontejneru. Spusťte nový exec z práce uložené v checkpointu.
Časový limit čekání vypršel nebo bylo čekání přerušeno, ale proces stále běží Pouze lokální čekání. Zavolejte kill() pokud ho máte v úmyslu zastavit.
Port nikdy není připravený Výchozí waitForPort režim je TCP. Použijte mode: "http" pro HTTP kontroly. Proces mohl skončit, zkontrolujte stav nebo logy.
Potřebujete interaktivní stdin Ne na handle procesu. Použijte terminál nebo neinteraktivní argv/cwd/env.

Terminály

Příznak Co zkontrolovat
Prohlížeč stále používá sessionId Pomocná funkce náhledu xterm očekává terminalId.
getTerminal je null Platí stejná pravidla životnosti jako pro procesy. Pokud byl kontejner nahrazen, vytvořte ho znovu.
Opětovné připojení nemá historii Předejte posledních cursor do connect / možnosti výstupu.

Prostředí a tajné údaje

Příznak Co zkontrolovat
Env z předchozího exec „zmizela“ Žádný shell relace. Použijte setEnvVars a/nebo pro jednotlivé spuštění env. Proměnné prostředí.
Úniky klíčů API do kontejneru Živé tajné údaje nevkládejte do sandbox env. Použijte odchozí provoz handlery na Workeru.

Interpreter

Příznak Co zkontrolovat
sandbox.createCodeContext is not a function Připojte withInterpreter a volejte sandbox.interpreter.*.
Python není k dispozici Použijte -python image varianta na stejné @next řádek.

Bridge HTTP

Příznak Co zkontrolovat
Bridge /exec, relace nebo /pty chování se liší od @next dokumentace Worker SDK Samostatně nasazený bridge není součástí náhledu 1.0. Použijte stabilní bridge s odpovídajícím stabilním balíčkem a obrazem kontejneru.

Agenti a dlouhotrvající úlohy

Pro agenty a dlouhoběžící nástroje na @next:

  1. Spuštění s exec(argv) (často ['/bin/bash', '-lc', script]).
  2. Čekejte pomocí waitForLog, waitForPort, nebo logs : nejen await exec.
  3. Uložit stav úlohy (příkaz, cwd, env, checkpoint), nejen process.id.
  4. Při pozdějším požadavku: getProcess(id) zatímco ho stejný kontejner může ještě obsahovat; jinak exec znovu.
  5. Použijte terminál pouze pokud potřebujete PTY pro člověka, ne jako náhradu relace.

Viz Provádění procesů, Migrace, a příklady v sandbox-sdk ↗ repo (claude-code, codex, opencode, a další).