cloudflare/sandbox-next

SDK Sandbox — @next (aperçu 1.0)

Environnements Linux isolés sur Cloudflare Containers, pilotés depuis des Workers.

Privilégiez la documentation d'aperçu et les types @next installés plutôt que la mémoire. Les API changent ; cette compétence est une passerelle, un contrat et une carte de récupération — pas un manuel complet.

Nous recommandons les nouveaux projets sur cette ligne. Les applications encore sur le package par défaut utilisent sandbox-stable. Portez uniquement sur demande, via sandbox-migrate-to-next.

1. Passerelle — confirmer la ligne de package

Avant d'écrire du code, inspectez l'application :

Vérification	Doit correspondre
Dépendance npm	@cloudflare/sandbox@next (ou un autre tag d'aperçu)
Image du conteneur	Même ligne (ex. cloudflare/sandbox:next, next-python)

Si vous trouvez…	Action
@cloudflare/sandbox par défaut (pas de @next)	Arrêtez. Chargez sandbox-stable. N'appliquez pas les API de cette compétence.
L'utilisateur souhaite porter stable → @next	Arrêtez. Chargez sandbox-migrate-to-next.
Bridge auto-déployé uniquement	Bridge n'est pas encore sur la ligne d'aperçu 1.0. Maintenez le bridge sur le package et l'image stables. Bridge (stable)

Ne mélangez jamais un package Worker @next avec une image de conteneur stable (ou l'inverse).

Installation des compétences : Configuration de l'agent · cloudflare/skills

2. Contrat — non négociable

• sandbox.exec(argv) prend une liste argv et se résout lorsque le processus démarre. Il retourne un handle, pas un résultat de commande terminé.
• Collectez les résultats avec les méthodes du handle : output(), logs(), waitForExit(), waitForPort(), waitForLog(), kill(signal?).
• Pas de shell implicite. La syntaxe shell nécessite un shell explicite, par ex. ["/bin/bash", "-lc", script].
• Chaque lancement est indépendant. Un cd / export dans un exec n'est pas visible pour le suivant. Passez cwd et env par lancement, ou un seul script shell.
• Les handles de processus n'ont pas de stdin. Utilisation interactive → terminaux (createTerminal + connect).
• Le timeout / AbortSignal d'attente locale annule l'attente uniquement. Ils ne tuent pas le processus. Utilisez kill ou le timeout distant d'exec.
• getProcess / listProcesses / getTerminal / listTerminals ne démarrent pas un conteneur ; ils retournent null / [] quand aucun n'est actif.
• Les ID de processus et de terminal appartiennent au conteneur actuel, pas pour toujours à un ID de sandbox. Pour un travail qui doit survivre à un remplacement, stockez la tâche complète (argv, cwd, env, état de l'application) — pas seulement un ID.
• Configuration non secrète uniquement dans setEnvVars / env du lancement. Les informations d'identification en direct restent dans le Worker ; utilisez des gestionnaires sortants lorsque le sandbox appelle des API externes.
• N'inventez pas d'API stables supprimées (gitCheckout sur le noyau, achèvement de exec par chaîne, exécution de session, sandbox.terminal(request)).
• N'utilisez pas une seule boucle de nouvelle tentative pour chaque erreur (voir la documentation sur les erreurs).

Forme minimale :

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

Documentation API spécifique aux tâches : references/api-quick-ref.md

Index des exemples (branche next) : references/examples.md

3. Récupérer — ouvrir la documentation pour la tâche

Récupérez la page avant d'implémenter. Les types @next installés l'emportent sur les suppositions.

Vous devez…	Ouvrir
Vous orienter / choisir l'aperçu	Aperçu 1.0
Premier Worker, wrangler, Dockerfile	Commencer
exec, handles, état de préparation, durabilité	Exécution de processus
Signatures API des processus	API des processus
ID du sandbox vs conteneur vs sommeil/destruction	Cycle de vie
cwd / env / setEnvVars	Environnement
PTY interactif / terminal navigateur	Terminaux · API des terminaux
Interpréteur de code Python/JS	Interpréteur · API de l'interpréteur
Modèle d'extensions	Extensions
Classes d'erreur et récupération	Erreurs · API des erreurs
Échecs courants	Dépannage
Hub API	Référence API
Fichiers, montages, sauvegardes, ports, tunnels, proxyToSandbox	Documentation principale pour les surfaces partagées (ignorez session/transport/sandbox.terminal stables uniquement) : Fichiers · Stockage / montages · Ports · Tunnels · Sauvegardes · Trafic sortant · Exposer des services · Production
Exemples d'applications	exemples sur next
Toujours sur le package stable	sandbox-stable · Documentation principale Sandbox
Portage d'une application stable existante	sandbox-migrate-to-next · Migrer

4. Avant de livrer

• Lockfile et Dockerfile sur la même ligne @next
• Vérification de types contre les types @next installés
• Aucun secret en direct dans l'environnement du sandbox
• Les noms d'hôte d'aperçu de production nécessitent un DNS wildcard sur un domaine personnalisé lors de l'utilisation de ces modèles d'URL