Skip to main content

​
Prerequisites

Before you begin, ensure you have:
1

Node.js 16.17.0 or later

Download and install Node.js if you haven’t already.
node --version  # Should be 16.17.0 or higher
2

Docker running locally

Docker is required for local development. The sandbox runs in containers that need Docker to build and run.Verify Docker is running:
docker --version
docker ps  # Should not error
3

Cloudflare account (for production)

For deploying to production, you’ll need a Cloudflare account. Local development works without an account.

​
Create a new project

The fastest way to get started is using the official template: 
npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal
cd my-sandbox
This creates a new project with:
  • The Sandbox SDK pre-configured
  • A minimal Worker example
  • Docker configuration
  • Wrangler configuration for deployment

​
Add to existing project

If you have an existing Cloudflare Workers project, you can add the Sandbox SDK manually.

​
Install the package

npm install @cloudflare/sandbox

​
Create a Dockerfile

Create a Dockerfile in your project root. You can use the default image or customize it:
Dockerfile
FROM ghcr.io/cloudflare/sandbox-sdk:latest

# Optional: Add custom dependencies
# RUN apt-get update && apt-get install -y your-package

# Optional: Install Python packages
# RUN pip install --no-cache-dir your-python-package
The default image includes Python 3.11, Node.js 20, Git, and common utilities. See the custom containers guide to add your own dependencies.

​
Configure Wrangler

Update your wrangler.jsonc (or wrangler.toml) to configure the Sandbox Durable Object:
wrangler.jsonc
{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-05-06",
  "compatibility_flags": ["nodejs_compat"],
  "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"
    }
  ]
}
The migrations section is required when first deploying a Durable Object. It tells Cloudflare to create the necessary infrastructure.

​
Update your Worker

Add the Sandbox export to your Worker code:
src/index.ts
import { getSandbox, type Sandbox } from '@cloudflare/sandbox';

// Export the Sandbox Durable Object class
export { Sandbox } from '@cloudflare/sandbox';

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

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
    
    // Your code here
    const result = await sandbox.exec('echo "Hello from Sandbox!"');
    
    return Response.json({ output: result.stdout });
  }
};

​
Verify installation

Test your setup locally: 
npm run dev
The first run builds the Docker container, which takes 2-3 minutes. Subsequent runs are much faster as the image is cached.
Once the dev server starts, test the sandbox: 
curl http://localhost:8787
You should see output from your sandbox execution.

​
TypeScript support

The SDK includes full TypeScript definitions. If you’re using TypeScript, ensure your tsconfig.json includes:
tsconfig.json
{
  "compilerOptions": {
    "types": ["@cloudflare/workers-types"]
  }
}
Generate types for your Wrangler configuration: 
npx wrangler types
This creates a worker-configuration.d.ts file with types for your environment bindings.

​
Next steps

Quickstart

Build your first sandbox application

API reference

Explore the complete SDK API

Build docs developers (and LLMs) love

Get started for freeTalk to us