Sandbox SDK — package stable

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

Préférez la documentation principale de Sandbox et les types stables installés à la mémoire. Cette skill est une porte, un contrat et une carte de récupération—pas un manuel complet.

Cette ligne est le package npm stable actuel par défaut. La documentation principale de Sandbox la décrit. Les apps existantes peuvent rester ici et continuer à livrer.

Nous recommandons les nouveaux projets sur @cloudflare/sandbox@next avec sandbox-next. Quand vous le pouvez, planifiez une migration avec sandbox-migrate-to-next pour être prêt quand 1.0 deviendra la version stable. Ne forcez pas ce port à moins que l'utilisateur ne le demande.

1. Porte — confirmer la ligne de package

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

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

Installation des skills : Agent setup · cloudflare/skills

2. Contrat — non négociables

• await sandbox.exec(command) prend une chaîne de commande et se résout quand la commande se termine, avec stdout / stderr / exitCode bufférisés (et champs connexes).
• Le travail long terme et le streaming utilisent les APIs de commandes stables (startProcess, execStream, et helpers connexes)—pas le modèle @next avec handle unique. Ouvrez la documentation Commands ; n'inventez pas les handles @next output() sur stable.
• Les sessions peuvent préserver le répertoire de travail et l'environnement entre les commandes (session par défaut / enableDefaultSession, createSession). Consultez la documentation Sessions quand l'état doit persister entre les appels.
• Les terminaux de navigateur interactifs utilisent souvent sandbox.terminal(request) et les helpers session/xterm sur stable—pas le preview createTerminal à moins que le package soit @next.
• Préférez le transport RPC quand vous utilisez des tunnels ou du streaming large/binaire. Les transports HTTP/WebSocket sont dépréciés (guide de nettoyage ci-dessous).
• Fichiers, montages, ports, tunnels, sauvegardes, cycle de vie et interpréteur : utilisez les docs principales pour les signatures ; fiez-vous aux types stables installés.
• Config non-secrète dans l'env sandbox ; credentials en direct dans le Worker. Utilisez les outbound handlers quand les processus appellent des APIs externes.
• Les hostnames preview en production ont besoin d'un DNS wildcard sur un domaine personnalisé lors de l'utilisation de ces patterns d'URL.
• N'appliquez pas les APIs @next argv/process.output() tant que la dépendance est encore stable.
• Le bridge auto-déployé reste sur le package et l'image stables. Bridge

Forme minimale :

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. Récupérer — ouvrir la doc pour la tâche

Récupérez la page avant d'implémenter. Les types stables installés gagnent sur les suppositions.

Nettoyage API dépréciée (rester sur stable)

Mettez d'abord à jour le package + l'image correspondante, puis suivez le guide. Recherche typique :

rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'

Ce chemin ne vous bascule pas vers @next.

4. Avant de livrer

• Package Worker et image de conteneur sur la même ligne stable
• Vérification de type par rapport aux types stables installés
• Pas de secrets en direct dans l'env sandbox
• Si vous utilisez les transports/helpers dépréciés, terminez ou suivez le nettoyage de la dépréciation 2026
• Quand l'équipe est prête pour 1.0, utilisez sandbox-migrate-to-next—ne forcez pas le basculement sans invite