cloudflare/sandbox-next

Sandbox SDK — @next (1.0 Vorschau)

Isolierte Linux-Umgebungen auf Cloudflare Containers, gesteuert von Workers.

Bevorzuge Vorschau-Dokumentationen und installierte @next-Typen gegenüber dem Gedächtnis. APIs ändern sich; dieser Skill ist ein Tor, ein Vertrag und eine Abrufkarte – kein vollständiges Handbuch.

Wir empfehlen neue Projekte auf dieser Linie. Apps, die noch auf dem Standardpaket laufen, verwenden sandbox-stable. Portiere nur, wenn du darum gebeten wirst, über sandbox-migrate-to-next.

1. Tor — Bestätige die Paketlinie

Bevor du Code schreibst, überprüfe die App:

Prüfung	Muss übereinstimmen
npm-Abhängigkeit	@cloudflare/sandbox@next (oder ein anderer Preview-Tag)
Container-Image	Gleiche Linie (z.B. cloudflare/sandbox:next, next-python)

Wenn du findest…	Aktion
Standard @cloudflare/sandbox (ohne @next)	Stop. Lade sandbox-stable. Wende die APIs dieses Skills nicht an.
Benutzer möchte stabil → @next portieren	Stop. Lade sandbox-migrate-to-next.
Selbst bereitgestellte Bridge nur	Bridge ist nicht auf der 1.0-Vorschau-Linie. Behalte Bridge auf stabilem Paket + Image. Bridge (stabil)

Mische niemals ein @next Worker-Paket mit einem stabilen Container-Image (oder umgekehrt).

Skills-Installation: Agent-Setup · cloudflare/skills

2. Vertrag — Nicht verhandelbar

• sandbox.exec(argv) akzeptiert eine argv-Liste und wird aufgelöst, wenn der Prozess startet. Es gibt einen Handle zurück, kein fertiges Befehlsergebnis.
• Sammle Ergebnisse mit Handle-Methoden: output(), logs(), waitForExit(), waitForPort(), waitForLog(), kill(signal?).
• Keine implizite Shell. Shell-Syntax benötigt eine explizite Shell, z.B. ["/bin/bash", "-lc", script].
• Jeder Start ist unabhängig. Ein cd / export in einem exec ist für den nächsten nicht sichtbar. Übergib cwd und env pro Start oder ein Shell-Skript.
• Prozess-Handles haben kein stdin. Interaktive Nutzung → Terminals (createTerminal + connect).
• Lokales Warte- timeout / AbortSignal bricht nur das Warten ab. Sie töten den Prozess nicht. Verwende kill oder das entfernte timeout von exec.
• getProcess / listProcesses / getTerminal / listTerminals starten keinen Container; sie geben null / [] zurück, wenn keiner läuft.
• Prozess- und Terminal-IDs gehören zum aktuellen Container, nicht für immer zu einer Sandbox-ID. Für Arbeiten, die einen Ersatz überdauern müssen, speichere den vollständigen Job (argv, cwd, env, App-Zustand) – nicht nur eine ID.
• Nicht-geheime Konfiguration nur in setEnvVars / Start-env. Live-Anmeldeinformationen bleiben im Worker; verwende ausgehende Handler, wenn die Sandbox externe APIs aufruft.
• Erfinde keine entfernten stabilen APIs (gitCheckout auf Kern, String-exec-Abschluss, Sitzungsausführung, sandbox.terminal(request)).
• Verwende keine einzige Wiederholungsschleife für jeden Fehler (siehe Fehlerdokumentation).

Minimale Form:

import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";

export { Sandbox };

const sandbox = getSandbox(env.Sandbox, "user-123");
const process = await sandbox.exec(["python3", "-c", "print(2 + 2)"]);
const result = await process.output({ encoding: "utf8" });
// result.stdout, result.exitCode

Aufgabenspezifische API-Dokumentation: references/api-quick-ref.md

Beispielindex (next-Branch): references/examples.md

3. Abrufen — Öffne die Dokumentation für die Aufgabe

Rufe die Seite ab, bevor du implementierst. Installierte @next-Typen gewinnen gegenüber Vermutungen.

Du musst…	Öffne
Orientieren / Vorschau wählen	1.0 Vorschau Übersicht
Erster Worker, wrangler, Dockerfile	Erste Schritte
exec, Handles, Bereitschaft, Haltbarkeit	Prozessausführung
Prozess-API-Signaturen	Prozesse API
Sandbox-ID vs. Container vs. Schlaf/Zerstören	Lebenszyklus
cwd / env / setEnvVars	Umgebung
Interaktives PTY / Browser-Terminal	Terminals · Terminals API
Python/JS-Interpreter	Interpreter · Interpreter API
Erweiterungsmodell	Erweiterungen
Fehlerklassen und Wiederherstellung	Fehler · Fehler API
Häufige Fehler	Fehlerbehebung
API-Hub	API-Referenz
Dateien, Mounts, Backups, Ports, Tunnel, proxyToSandbox	Hauptdokumentation für gemeinsame Oberflächen (ignoriere stabil-only Sitzung/Transport/sandbox.terminal): Dateien · Speicher / Mounts · Ports · Tunnel · Backups · Ausgehender Verkehr · Dienste verfügbar machen · Produktion
Beispiel-Apps	Beispiele auf next
Noch auf stabilem Paket	sandbox-stable · Haupt-Sandbox-Dokumentation
Portieren einer bestehenden stabilen App	sandbox-migrate-to-next · Migrieren

4. Vor dem Ausliefern

• Lockfile und Dockerfile auf der gleichen @next-Linie
• Typprüfung gegen installierte @next-Typen
• Keine Live-Geheimnisse in der Sandbox-Umgebung
• Production-Preview-Hostnamen benötigen Wildcard-DNS auf einer benutzerdefinierten Domain, wenn diese URL-Muster verwendet werden