Skip to content
Cloudflare Docs

Wrangler configuration

Minimal configuration

The minimum required configuration for using Sandbox SDK:

{
  "name": "my-sandbox-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-13",
  "compatibility_flags": ["nodejs_compat"],
  "containers": [
    {
      "class_name": "Sandbox",
      "image": "./Dockerfile",
    },
  ],
  "durable_objects": {
    "bindings": [
      {
        "class_name": "Sandbox",
        "name": "Sandbox",
      },
    ],
  },
  "migrations": [
    {
      "new_sqlite_classes": ["Sandbox"],
      "tag": "v1",
    },
  ],
}

Required settings

The Sandbox SDK is built on Cloudflare Containers. Your configuration requires three sections:

  1. containers - Define the container image (your runtime environment)
  2. durable_objects.bindings - Bind the Sandbox Durable Object to your Worker
  3. migrations - Initialize the Durable Object class

The minimal configuration shown above includes all required settings. For detailed configuration options, refer to the Containers configuration documentation.

Troubleshooting

Binding not found

Error: TypeError: env.Sandbox is undefined

Solution: Ensure your wrangler.jsonc includes the Durable Objects binding:

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

Missing migrations

Error: Durable Object not initialized

Solution: Add migrations for the Sandbox class:

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