1# Cloudflare Sandbox SDK
2 
3Secure isolated code execution in containers on Cloudflare's edge. Run untrusted code, manage files, expose services, integrate with AI agents.
4 
5**Use cases**: AI code execution, interactive dev environments, data analysis, CI/CD, code interpreters, multi-tenant execution.
6 
7## Architecture
8 
9- Each sandbox = Durable Object + Container
10- Persistent across requests (same ID = same sandbox)
11- Isolated filesystem/processes/network
12- Configurable sleep/wake for cost optimization
13 
14## Quick Start
15 
16```typescript
17import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox';
18export { Sandbox } from '@cloudflare/sandbox';
19 
20type Env = { Sandbox: DurableObjectNamespace<Sandbox>; };
21 
22export default {
23  async fetch(request: Request, env: Env): Promise<Response> {
24    // CRITICAL: proxyToSandbox MUST be called first for preview URLs
25    const proxyResponse = await proxyToSandbox(request, env);
26    if (proxyResponse) return proxyResponse;
27 
28    const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
29    const result = await sandbox.exec('python3 -c "print(2 + 2)"');
30    return Response.json({ output: result.stdout });
31  }
32};
33```
34 
35**wrangler.jsonc**:
36```jsonc
37{
38  "name": "my-sandbox-worker",
39  "main": "src/index.ts",
40  "compatibility_date": "2025-01-01", // Use current date for new projects
41  
42  "containers": [{
43    "class_name": "Sandbox",
44    "image": "./Dockerfile",
45    "instance_type": "lite",        // lite | standard | heavy
46    "max_instances": 5
47  }],
48  
49  "durable_objects": {
50    "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }]
51  },
52  
53  "migrations": [{
54    "tag": "v1",
55    "new_sqlite_classes": ["Sandbox"]
56  }]
57}
58```
59 
60**Dockerfile**:
61```dockerfile
62FROM docker.io/cloudflare/sandbox:0.7.0
63RUN pip3 install --no-cache-dir pandas numpy matplotlib
64EXPOSE 8080 3000  # Required for wrangler dev
65```
66 
67## Core APIs
68 
69- `getSandbox(namespace, id, options?)` → Get/create sandbox
70- `sandbox.exec(command, options?)` → Execute command
71- `sandbox.readFile(path)` / `writeFile(path, content)` → File ops
72- `sandbox.startProcess(command, options)` → Background process
73- `sandbox.exposePort(port, options)` → Get preview URL
74- `sandbox.createSession(options)` → Isolated session
75- `sandbox.wsConnect(request, port)` → WebSocket proxy
76- `sandbox.destroy()` → Terminate container
77- `sandbox.mountBucket(bucket, path, options)` → Mount S3 storage
78 
79## Critical Rules
80 
81- ALWAYS call `proxyToSandbox()` first
82- Same ID = reuse sandbox
83- Use `/workspace` for persistent files
84- `normalizeId: true` for preview URLs
85- Retry on `CONTAINER_NOT_READY`
86 
87## In This Reference
88- [configuration.md](./configuration.md) - Config, CLI, environment setup
89- [api.md](./api.md) - Programmatic API, testing patterns
90- [patterns.md](./patterns.md) - Common workflows, CI/CD integration
91- [gotchas.md](./gotchas.md) - Issues, limits, best practices
92 
93## See Also
94- [durable-objects](../durable-objects/) - Sandbox runs on DO infrastructure
95- [containers](../containers/) - Container runtime fundamentals
96- [workers](../workers/) - Entry point for sandbox requests
97