Sandbox SDK — @next (aperçu 1.0)

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

Privilégiez les docs d'aperçu et les types @next installés par rapport à la mémoire. Les APIs changent ; cette skill est une porte, un contrat et une carte de récupération—pas un manuel complet.

Nous recommandons les nouveaux projets sur cette ligne. Les apps encore sur le package par défaut utilisent sandbox-stable. Migrez seulement si demandé, via sandbox-migrate-to-next.

1. Porte — confirmer la ligne de package

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

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

Installation des skills : Agent setup · cloudflare/skills

2. Contrat — non-négociables

• sandbox.exec(argv) prend une liste argv et se résout quand le processus démarre. Elle retourne un handle, pas un résultat de commande terminée.
• Récupérez les résultats avec les méthodes du handle : output(), logs(), waitForExit(), waitForPort(), waitForLog(), kill(signal?).
• Pas de shell implicite. La syntaxe shell a besoin d'un shell explicite, ex. ["/bin/bash", "-lc", script].
• Chaque lancement est indépendant. Un cd / export dans un exec n'est pas visible au suivant. Passez cwd et env par lancement, ou un script shell unique.
• Les process handles n'ont pas de stdin. Utilisation interactive → terminaux (createTerminal + connect).
• timeout local / AbortSignal annulent l'attente seulement. Ils ne tuent pas le processus. Utilisez kill ou le timeout distant d'exec.
• getProcess / listProcesses / getTerminal / listTerminals ne démarrent pas un container ; ils retournent null / [] quand aucun n'est actif.
• Les IDs de processus et terminal appartiennent au container courant, pas à jamais au sandbox ID. Pour du travail qui doit survivre au remplacement, stockez le job complet (argv, cwd, env, état app)—pas seulement un id.
• Config non-secrète seulement dans setEnvVars / env de lancement. Les credentials en direct restent dans le Worker ; utilisez les outbound handlers quand le sandbox appelle des APIs externes.
• Ne pas inventer les APIs stable supprimées (gitCheckout sur core, complétude string-exec, session execution, sandbox.terminal(request)).
• Ne pas utiliser une boucle retry pour chaque erreur (voir docs Errors).

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

Pense-bête optionnel non-exhaustif (process/terminal/interpreter seulement) : references/api-quick-ref.md
Index des exemples (branche next) : references/examples.md

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

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

4. Avant de déployer

• Lockfile et Dockerfile sur la même ligne @next
• Typecheck par rapport aux types @next installés
• Pas de secrets en direct dans l'env du sandbox
• Les hostnames d'aperçu en production ont besoin de DNS wildcard sur un domaine personnalisé quand vous utilisez ces patterns d'URL