cloudflare-sandbox

# Cloudflare Sandboxes SDK

**Status**: Production Ready (Open Beta)
**Last Updated**: 2025-12-10
**Dependencies**: `cloudflare-worker-base`, `cloudflare-durable-objects` (recommended for understanding)
**Latest Versions**: `@cloudflare/sandbox@0.6.3`, Docker image: `cloudflare/sandbox:0.6.3-python`

**⚠️ BREAKING CHANGE (v0.6.0):** Python is no longer included in the default image. Use `cloudflare/sandbox:<version>-python` for Python support (~1.3GB with data science packages). The lean variant (~600-800MB) excludes Python.

---

## Quick Start (15 Minutes)

### 1. Install SDK and Setup Wrangler

```bash
bun add @cloudflare/sandbox@latest  # preferred
# or: bun add @cloudflare/sandbox@latest
```

**wrangler.jsonc:**
```jsonc
{
  "name": "my-sandbox-worker",
  "main": "src/index.ts",
  "compatibility_flags": ["nodejs_compat"],
  "containers": [{
    "class_name": "Sandbox",
    "image": "cloudflare/sandbox:0.6.3-python",
    "instance_type": "lite"
  }],
  "durable_objects": {
    "bindings": [{
      "class_name": "Sandbox",
      "name": "Sandbox"
    }]
  },
  "migrations": [{
    "tag": "v1",
    "new_sqlite_classes": ["Sandbox"]
  }]
}
```

**Why this matters:**
- `nodejs_compat` enables Node.js APIs required by SDK
- `containers` defines the Ubuntu container image
- `durable_objects` binding enables persistent routing
- `migrations` registers the Sandbox class

### 2. Create Your First Sandbox Worker

```typescript
import { getSandbox, 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> {
    // Get sandbox instance (creates if doesn't exist)
    const sandbox = getSandbox(env.Sandbox, 'my-first-sandbox');

    // Execute Python code
    const result = await sandbox.exec('python3 -c "print(2 + 2)"');

    return Response.json({
      output: result.stdout,
      success: result.success