Wrangler configuration (2)

Last updated Oct 12, 2026 Note

This page documents Sandbox SDK 0.x for existing applications. For new applications, refer to Sandboxes. To move an existing application to @cloudflare/sandbox 1.0, refer to Migrate from Sandbox SDK 0.x.

Minimal configuration

The minimum required configuration for using Sandbox SDK:

{
    "name": "my-sandbox-worker",
    "main": "src/index.ts",
    "upload_source_maps": true,
    // Set this to today's date
    "compatibility_date": "2026-10-27",
    "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",
        },
    ],
}

name = "my-sandbox-worker"
main = "src/index.ts"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-10-27"
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.

Backup storage

To use the backup and restore API, you need an R2 bucket binding and presigned URL credentials. The container uploads and downloads backup archives directly to/from R2 using presigned URLs, which requires R2 API token credentials.

1. Create the R2 bucket

npx wrangler r2 bucket create my-backup-bucket

2. Add the binding and environment variables

{
    "vars": {
        "BACKUP_BUCKET_NAME": "my-backup-bucket",
        "CLOUDFLARE_ACCOUNT_ID": "<YOUR_ACCOUNT_ID>",
    },
    "r2_buckets": [
        {
            "binding": "BACKUP_BUCKET",
            "bucket_name": "my-backup-bucket",
        },
    ],
}

[vars]
BACKUP_BUCKET_NAME = "my-backup-bucket"
CLOUDFLARE_ACCOUNT_ID = "<YOUR_ACCOUNT_ID>"

[[r2_buckets]]
binding = "BACKUP_BUCKET"
bucket_name = "my-backup-bucket"

3. Set R2 API credentials as secrets

npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY

Create an R2 API token in the Cloudflare dashboard ↗︎ under R2 > Overview > Manage R2 API Tokens. The token needs Object Read & Write permissions for your backup bucket.

The SDK uses these credentials to generate presigned URLs that allow the container to transfer backup archives directly to and from R2. For a complete setup walkthrough, refer to the backup and restore guide.

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",
            },
        ],
    },
}

[[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",
        },
    ],
}

[[migrations]]
new_sqlite_classes = [ "Sandbox" ]
tag = "v1"

Was this helpful?

YesNo

On this page

Wrangler configuration (2) - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/sandbox/sdk/configuration/wrangler/#page","headline":"Wrangler configuration","description":"Set up Wrangler bindings, Durable Objects, and container settings for Sandbox SDK 0.x.","url":"https://developers.cloudflare.com/sandbox/sdk/configuration/wrangler/","inLanguage":"en","image":"https://developers.cloudflare.com/sandbox/sdk/configuration/wrangler/og.png?v=b26847ea7d347dba","dateModified":"2026-10-12","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Create your first Sandbox SDK 0.x Worker to execute Python code in isolated containers. title: Getting started image: https://developers.cloudflare.com/sandbox/sdk/get-started/og.png?v=00c05b54db8459dc

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/sandbox/llms.txt
Use this file to discover all available pages before exploring further.