sandbox-sdk

Construisez des applications sandboxées pour l'exécution sécurisée du code. Chargez lors de la création d'exécution de code AI, d'interpréteurs de code, de systèmes CI/CD, d'environnements de développement interactifs ou d'exécution de code non fiable. Couvre le cycle de vie du Sandbox SDK, les commandes, les fichiers, l'interpréteur de code et les URL d'aperçu. Privilégie la récupération à partir de la documentation Cloudflare par rapport aux connaissances pré-entraînées.

npx skills add https://github.com/cloudflare/skills --skill sandbox-sdk

Cloudflare Sandbox SDK

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

FIRST: Vérifiez l'installation

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

Sources de récupération

Vos connaissances du Sandbox SDK peuvent être obsolètes. Préférez la récupération à la pré-formation pour toute tâche du Sandbox SDK.

Ressource URL
Docs https://developers.cloudflare.com/sandbox/
Référence API https://developers.cloudflare.com/sandbox/api/
Exemples https://github.com/cloudflare/sandbox-sdk/tree/main/examples
Démarrage https://developers.cloudflare.com/sandbox/get-started/

Lors de la mise en œuvre 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 Worker - doit réexporter la classe Sandbox :

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

Référence rapide

Tâche Méthode
Obtenir sandbox getSandbox(env.Sandbox, 'user-123')
Exécuter une commande await sandbox.exec('python script.py')
Exécuter du code (interpréteur) await sandbox.runCode(code, { language: 'python' })
Écrire un fichier await sandbox.writeFile('/workspace/app.py', content)
Lire un fichier await sandbox.readFile('/workspace/app.py')
Créer un répertoire await sandbox.mkdir('/workspace/src', { recursive: true })
Lister les fichiers await sandbox.listFiles('/workspace')
Exposer un port await sandbox.exposePort(8080)
Détruire await sandbox.destroy()

Motifs fondamentaux

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 enrichies :

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 les 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

Besoin Utiliser Pourquoi
Commandes shell, scripts exec() Contrôle direct, streaming
Code généré par LLM runCode() Sorties enrichies, persistance d'état
Pipelines de build/test exec() Codes de sortie, capture stderr
Analyse de données runCode() Graphiques, tableaux, pandas

Extension du 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 légères - affecte le temps de démarrage à froid.

URL d'aperçu (Exposition de port)

Exposez les services HTTP s'exécutant dans les sandboxes :

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

Exigence de production : Les URL d'aperçu ont besoin d'un domaine personnalisé avec DNS wildcard (*.yourdomain.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 assistants pour OpenAI Agents à @cloudflare/sandbox/openai :

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

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

Cycle de vie du Sandbox

  • getSandbox() retourne immédiatement - le conteneur démarre paresseusement à 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 les ressources immédiatement
  • 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 - Worker ne se déploiera pas sans export { Sandbox }
  • Ne codez pas en dur les IDs de 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