Cloudflare Sandbox SDK

Créez des environnements d'exécution de code sécurisés et isolés sur Cloudflare Workers.

D'ABORD : Vérifier l'installation

npm install @cloudflare/sandbox
docker info  # Doit réussir - Docker requis pour le développement local

Sources de récupération

Votre connaissance du Sandbox SDK peut être obsolète. Préférez la récupération à la pré-formation pour toute tâche du Sandbox SDK.

Lors de l'implémentation de fonctionnalités, récupérez d'abord la page de documentation ou l'exemple pertinent.

Configuration requise

wrangler.jsonc (exact - ne modifiez pas la structure) :

{
  "containers": [{
    "class_name": "Sandbox",
    "image": "./Dockerfile",
    "instance_type": "lite",
    "max_instances": 1
  }],
  "durable_objects": {
    "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }]
  },
  "migrations": [{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" }]
}

Entrée du Worker - doit ré-exporter la classe Sandbox :

import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';  // Export requis

Référence rapide

Motifs principaux

Exécuter des commandes

const sandbox = getSandbox(env.Sandbox, 'user-123');
const result = await sandbox.exec('python --version');
// result: { stdout, stderr, exitCode, success }

Interpréteur de code (recommandé pour l'IA)

Utilisez runCode() pour exécuter du code généré par LLM avec des sorties riches :

const ctx = await sandbox.createCodeContext({ language: 'python' });

await sandbox.runCode('import pandas as pd; data = [1,2,3]', { context: ctx });
const result = await sandbox.runCode('sum(data)', { context: ctx });
// result.results[0].text = "6"

Langages : python, javascript, typescript

L'état persiste au sein du contexte. Créez des contextes explicites pour la production.

Opérations sur fichiers

await sandbox.mkdir('/workspace/project', { recursive: true });
await sandbox.writeFile('/workspace/project/main.py', code);
const file = await sandbox.readFile('/workspace/project/main.py');
const files = await sandbox.listFiles('/workspace/project');

Quand utiliser quoi

Étendre le Dockerfile

L'image de base (docker.io/cloudflare/sandbox:0.7.0) inclut Python 3.11, Node.js 20 et les outils courants.

Ajoutez des dépendances en étendant le Dockerfile :

FROM docker.io/cloudflare/sandbox:0.7.0

# Paquets Python
RUN pip install requests beautifulsoup4

# Paquets Node (global)
RUN npm install -g typescript

# Paquets système
RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*

EXPOSE 8080  # Requis pour l'exposition du port en développement local

Gardez les images allégées - affecte le temps de démarrage à froid.

URLs d'aperçu (exposition de port)

Exposez les services HTTP exécutés dans les sandboxes :

const { url } = await sandbox.exposePort(8080);
// Retourne l'URL d'aperçu du service

Exigence de production : Les URLs d'aperçu nécessitent un domaine personnalisé avec DNS wildcard (*.votredomaine.com). Le domaine .workers.dev ne supporte pas les sous-domaines d'URL d'aperçu.

Voir : https://developers.cloudflare.com/sandbox/guides/expose-services/

Intégration avec OpenAI Agents SDK

Le SDK fournit des helpers pour OpenAI Agents à @cloudflare/sandbox/openai :

import { Shell, Editor } from '@cloudflare/sandbox/openai';

Consultez examples/openai-agents pour le motif d'intégration complet.

Cycle de vie de Sandbox

• getSandbox() retourne immédiatement - le conteneur démarre en lazy loading lors de la première opération
• Les conteneurs se mettent en veille après 10 minutes d'inactivité (configurable via sleepAfter)
• Utilisez destroy() pour libérer immédiatement les ressources
• Le même sandboxId retourne toujours la même instance de sandbox

Anti-motifs

• N'utilisez pas les clients internes (CommandClient, FileClient) - utilisez les méthodes sandbox.*
• Ne sautez pas l'export Sandbox - le Worker ne sera pas déployé sans export { Sandbox }
• Ne codez pas en dur les IDs sandbox pour multi-utilisateur - utilisez des identifiants utilisateur/session
• N'oubliez pas le nettoyage - appelez destroy() pour les sandboxes temporaires

Références détaillées

• references/api-quick-ref.md - API complète avec options et types de retour
• references/examples.md - Index d'exemples avec cas d'usage