Sandbox SDK — stabiles Paket
Isolierte Linux-Umgebungen auf Cloudflare Containers, gesteuert von Workers aus.
Bevorzuge die Haupt-Sandbox-Dokumentation und installierten stabilen Typen gegenüber dem Gedächtnis. Dieses Skill ist ein Gate, ein Vertrag und eine Abrufkarte – kein vollständiges Handbuch.
Diese Zeile ist das aktuelle stabile Standard-npm-Paket. Die Hauptdokumentation von Sandbox beschreibt es. Bestehende Apps können hier bleiben und weiter ausgeliefert werden.
Wir empfehlen neue Projekte auf @cloudflare/sandbox@next mit sandbox-next. Plane, wenn möglich, einen Wechsel mit sandbox-migrate-to-next, damit du bereit bist, wenn 1.0 zur stabilen Version wird. Erzwinge diesen Port nicht, es sei denn, der Nutzer fragt danach.
1. Gate — bestätige die Paketlinie
Prüfe die App, bevor du Code schreibst:
| Prüfung | Muss übereinstimmen |
|---|---|
| npm-Abhängigkeit | Standard @cloudflare/sandbox (nicht @next / Vorschau-Tags) |
| Container-Image | Passendes stabiles Image (nicht cloudflare/sandbox:next) |
| Wenn du findest… | Aktion |
|---|---|
@cloudflare/sandbox@next oder ein next-Image | Stopp. Lade sandbox-next. |
Nutzer möchte auf 1.0 / @next portieren | Stopp. Lade sandbox-migrate-to-next. Wende keine Vorschau-APIs auf ein stabiles Paket an. |
| Nur Bereinigung veralteter stabiler APIs | Bleib hier; verwende den Deprecation-Leitfaden 2026. Das ist kein Wechsel zu @next. |
Mische niemals ein stabiles Worker-Paket mit einem @next-Container-Image (oder umgekehrt).
Installation der Skills: Agent-Setup · cloudflare/skills
2. Vertrag — nicht verhandelbar
await sandbox.exec(command)akzeptiert einen Befehl als Zeichenkette und wird aufgelöst, wenn der Befehl beendet ist, mit gepuffertenstdout- /stderr- /exitCode-Werten (und verwandten Feldern).- Langlaufende und Streaming-Aufgaben verwenden die stabilen Befehls-APIs (
startProcess,execStreamund verwandte Hilfsfunktionen) – nicht das@next-Einzel-Handle-Modell. Öffne die Befehlsdokumentation; erfinde keine@next-output()-Handles auf stable. - Sitzungen können das Arbeitsverzeichnis und die Umgebung über Befehle hinweg erhalten (Standard-Sitzung /
enableDefaultSession,createSession. Siehe Sitzungsdokumentation, wenn der Zustand über Aufrufe hinweg beibehalten werden muss. - Interaktive Browser-Terminals verwenden oft
sandbox.terminal(request)sowie Sitzungs-/xterm-Hilfsfunktionen auf stable – nicht das Vorschau-createTerminal, es sei denn, das Paket ist@next. - Bevorzuge RPC-Transport, wenn du Tunnel oder große/binäre Streams verwendest. HTTP/WebSocket-Transporte sind veraltet (Bereinigungsanleitung unten).
- Dateien, Mounts, Ports, Tunnel, Backups, Lebenszyklus und Interpreter: Verwende die Hauptdokumentation für Signaturen; vertraue den installierten stabilen Typen.
- Nicht geheime Konfiguration in der Sandbox-Umgebung; Live-Zugangsdaten im Worker. Verwende ausgehende Handler, wenn Prozesse externe APIs aufrufen.
- Produktions-Vorschau-Hostnamen benötigen Wildcard-DNS auf einer benutzerdefinierten Domain, wenn diese URL-Muster verwendet werden.
- Wende nicht
@next-argv/process.output()-APIs an, während die Abhängigkeit noch stabil ist. - Selbst bereitgestellter Bridge bleibt auf dem stabilen Paket und Image. Bridge
Minimale Form:
import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";
export { Sandbox };
const sandbox = getSandbox(env.Sandbox, "user-123");
const result = await sandbox.exec('python3 -c "print(2 + 2)"');
// result.stdout, result.exitCode, result.success
3. Abrufen — öffne die Dokumentation für die Aufgabe
Rufe die Seite ab, bevor du implementierst. Installierte stabile Typen gewinnen über Vermutungen.
| Du musst… | Öffne |
|---|---|
| Orientierung | Sandbox-Übersicht |
| Erster Worker, Template, Docker | Erste Schritte |
exec, Streaming, Hintergrundprozesse | Befehls-API · Befehle ausführen · Hintergrundprozesse · Streaming-Ausgabe |
| Sitzungen / Shell-Zustand über Befehle hinweg | Sitzungen-Konzept · Sitzungen-API |
getSandbox-Optionen, Schlaf, Zerstören | Lebenszyklus-API · Sandbox-Optionen |
| Umgebungsvariablen | Umgebungsvariablen |
| Dateien | Dateien-API · Dateien verwalten · Dateiüberwachung |
| Buckets / Mounts | Speicher-API · Buckets einbinden |
| Backups | Backups-API · Sichern und Wiederherstellen |
| Ports, Vorschau-URLs, Freigeben | Ports-API · Dienste freigeben |
| Tunnel | Tunnel-API |
| Proxy / Worker-Verbindungen | Proxy-Anfragen · Worker-Verbindungen |
| Browser / PTY-Terminal | Terminal-API · Terminal-Konzept · Browser-Terminals |
| Code-Interpreter | Interpreter-API · Code-Ausführung |
| Git in der Sandbox | Git-Workflows |
| Geheimnisse / ausgehender Datenverkehr | Ausgehender Datenverkehr |
| WebSockets | WebSocket-Verbindungen |
| Docker-in-Docker | Docker in Docker |
| Produktionsbereitstellung | Produktionsbereitstellung |
| Container-Konzept | Container |
| How-to-Index | Anleitungen |
| API-Index | API-Referenz |
| Veraltete APIs während du auf stable bleibst | Deprecation-Leitfaden 2026 |
| Selbst bereitgestellter Bridge | Bridge · Bridge-HTTP-API |
Beispiele (stable/main) | Beispiele auf GitHub |
| Neue Arbeit an der 1.0-Vorschau | sandbox-next · 1.0-Vorschau |
Bestehende App zu @next portieren | sandbox-migrate-to-next · Migrieren |
Bereinigung veralteter APIs (auf stable bleiben)
Aktualisiere zuerst das Paket und das passende Image, folge dann der Anleitung. Typische Suche:
rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'
Dieser Pfad wechselt dich nicht zu @next.
4. Vor dem Ausliefern
- Worker-Paket und Container-Image auf der gleichen stabilen Linie
- Typ-Check gegen installierte stabile Typen
- Keine Live-Geheimnisse in der Sandbox-Umgebung
- Wenn veraltete Transporte/Hilfsfunktionen verwendet werden, abschließen oder Bereinigung gemäß Deprecation 2026 verfolgen
- Wenn das Team bereit für 1.0 ist,
sandbox-migrate-to-nextverwenden – keine erzwungene Umstellung ohne Aufforderung