openai-cloudflare-deploy/references/sandbox/README.md

Cloudflare Sandbox SDK

Secure isolated code execution in containers on Cloudflare's edge. Run untrusted code, manage files, expose services, integrate with AI agents.

Use cases: AI code execution, interactive dev environments, data analysis, CI/CD, code interpreters, multi-tenant execution.

Architecture

• Each sandbox = Durable Object + Container
• Persistent across requests (same ID = same sandbox)
• Isolated filesystem/processes/network
• Configurable sleep/wake for cost optimization

Quick Start

import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';

type Env = { Sandbox: DurableObjectNamespace<Sandbox>; };

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // CRITICAL: proxyToSandbox MUST be called first for preview URLs
    const proxyResponse = await proxyToSandbox(request, env);
    if (proxyResponse) return proxyResponse;

    const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
    const result = await sandbox.exec('python3 -c "print(2 + 2)"');
    return Response.json({ output: result.stdout });
  }
};

wrangler.jsonc:

{
  "name": "my-sandbox-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01", // Use current date for new projects

  "containers": [{
    "class_name": "Sandbox",
    "image": "./Dockerfile",
    "instance_type": "lite",        // lite | standard | heavy
    "max_instances": 5
  }],

  "durable_objects": {
    "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }]
  },

  "migrations": [{
    "tag": "v1",
    "new_sqlite_classes": ["Sandbox"]
  }]
}

Dockerfile:

FROM docker.io/cloudflare/sandbox:latest
RUN pip3 install --no-cache-dir pandas numpy matplotlib
EXPOSE 8080 3000  # Required for wrangler dev

Core APIs

• getSandbox(namespace, id, options?) → Get/create sandbox
• sandbox.exec(command, options?) → Execute command
• sandbox.readFile(path) / writeFile(path, content) → File ops
• sandbox.startProcess(command, options) → Background process
• sandbox.exposePort(port, options) → Get preview URL
• sandbox.createSession(options) → Isolated session
• sandbox.wsConnect(request, port) → WebSocket proxy
• sandbox.destroy() → Terminate container
• sandbox.mountBucket(bucket, path, options) → Mount S3 storage

Critical Rules

• ALWAYS call proxyToSandbox() first
• Same ID = reuse sandbox
• Use /workspace for persistent files
• normalizeId: true for preview URLs
• Retry on CONTAINER_NOT_READY

In This Reference

• configuration.md - Config, CLI, environment setup
• api.md - Programmatic API, testing patterns
• patterns.md - Common workflows, CI/CD integration
• gotchas.md - Issues, limits, best practices

See Also

• durable-objects - Sandbox runs on DO infrastructure
• containers - Container runtime fundamentals
• workers - Entry point for sandbox requests