cloudflare/sandbox-stable

SDK Sandbox — 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 plutôt que la mémoire. Ce skill est une porte d'entrée, 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 Sandbox principale la décrit. Les applications existantes peuvent rester ici et continuer à être livrées.

Nous recommandons les nouveaux projets sur @cloudflare/sandbox@next avec sandbox-next. Quand vous le pouvez, planifiez un déplacement avec sandbox-migrate-to-next pour être prêt lorsque la version 1.0 deviendra la version stable. Ne forcez pas ce portage sauf si l'utilisateur le demande.

1. Porte d'entrée — confirmer la ligne de package

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

Vérification	Doit correspondre à
Dépendance npm	@cloudflare/sandbox par défaut (pas les tags @next / preview)
Image conteneur	Image stable correspondante (pas cloudflare/sandbox:next)

Si vous trouvez…	Action
@cloudflare/sandbox@next ou une image next	Arrêtez. Chargez sandbox-next.
L'utilisateur veut porter vers 1.0 / @next	Arrêtez. Chargez sandbox-migrate-to-next. N'appliquez pas partiellement des API de prévisualisation sur un package stable.
Nettoyage d'API stables dépréciées uniquement	Restez ici ; utilisez le guide de dépréciation 2026. Ce n'est pas un passage à @next.

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

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

2. Contrat — non-négociables

• await sandbox.exec(command) prend une chaîne de commande et se résout lorsque la commande se termine, avec stdout / stderr / exitCode mis en mémoire tampon (et champs associés).
• Les travaux longue durée et en streaming utilisent les API de commandes stables (startProcess, execStream et aides associées) — pas le modèle à handle unique de @next. Ouvrez la documentation sur les commandes ; n'inventez pas de handles @next output() sur le 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 sur les sessions lorsque l'état doit être conservé entre les appels.
• Les terminaux de navigateur interactifs utilisent souvent sandbox.terminal(request) et les aides session/xterm sur le stable — pas createTerminal de prévisualisation sauf si le package est @next.
• Préférez le transport RPC lors de l'utilisation de tunnels ou de streaming volumineux/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 la documentation principale pour les signatures ; faites confiance aux types stables installés.
• Configuration non secrète dans l'environnement sandbox ; informations d'identification en direct dans le Worker. Utilisez les gestionnaires de trafic sortant lorsque les processus appellent des API externes.
• Les noms d'hôte de prévisualisation de production nécessitent un DNS générique sur un domaine personnalisé lors de l'utilisation de ces modèles d'URL.
• N'appliquez pas les API @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ération — ouvrir la documentation pour la tâche

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

Vous devez…	Ouvrez
Vous orienter	Vue d'ensemble Sandbox
Premier Worker, template, Docker	Démarrage
exec, streaming, processus en arrière-plan	API Commandes · Exécuter des commandes · Processus en arrière-plan · Sortie en streaming
Sessions / état du shell entre les commandes	Concept de sessions · API Sessions
Options getSandbox, mise en veille, destruction	API Cycle de vie · Options Sandbox
Variables d'environnement	Variables d'environnement
Fichiers	API Fichiers · Gérer les fichiers · Surveillance de fichiers
Buckets / montages	API Stockage · Monter des buckets
Sauvegardes	API Sauvegardes · Sauvegarder et restaurer
Ports, URL de prévisualisation, exposition	API Ports · Exposer des services
Tunnels	API Tunnels
Proxy / connexions Workers	Requêtes proxy · Connexions Workers
Terminal navigateur / PTY	API Terminal · Concept de terminal · Terminaux navigateur
Interpréteur de code	API Interpréteur · Exécution de code
Git dans le sandbox	Workflows Git
Secrets / trafic sortant	Trafic sortant
WebSockets	Connexions WebSocket
Docker-in-Docker	Docker dans Docker
Déploiement en production	Déploiement en production
Concept de conteneurs	Conteneurs
Index des guides	Guides
Index des API	Référence API
API dépréciées tout en restant sur stable	Guide de dépréciation 2026
Bridge auto-déployé	Bridge · API HTTP du Bridge
Exemples (stable/main)	exemples sur GitHub
Nouveau travail sur prévisualisation 1.0	sandbox-next · Prévisualisation 1.0
Porter une application existante vers @next	sandbox-migrate-to-next · Migrer

Nettoyage des API dépréciées (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 conteneur sur la même ligne stable
• Vérification de type contre les types stables installés
• Pas de secrets en direct dans l'environnement sandbox
• Si vous utilisez des transports/aides dépréciés, terminez ou suivez le nettoyage de la dépréciation 2026
• Lorsque l'équipe est prête pour la version 1.0, utilisez sandbox-migrate-to-next — ne forcez pas la transition sans demande