Getting started (13)

Last updated Sep 30, 2026 Note

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

Build your first application with Sandbox SDK - a secure code execution environment. In this guide, you'll create a Worker that can execute Python code and work with files in isolated containers.

What you're building

A simple API that can safely execute Python code and perform file operations in isolated sandbox environments.

Prerequisites

  1. Sign up for a Cloudflare account ↗︎.
  2. Install Node.js ↗︎.

<details>

<summary>

Node.js version manager

</summary>

Use <a href="https://viteplus.dev/guide/env">Vite+ (<code>vp env</code>) ↗︎</a> to install and manage Node.js versions.

For supported Node.js versions, refer to the <a href="https://developers.cloudflare.com/workers/wrangler/install-and-update/#install-wrangler">Wrangler system requirements</a>.

</details>

Ensure Docker is running locally

Sandbox SDK uses Docker ↗︎ to build container images alongside your Worker.

You must have Docker running locally when you run wrangler deploy. For most people, the best way to install Docker is to follow the docs for installing Docker Desktop ↗︎. Other tools like Colima ↗︎ may also work.

You can check that Docker is running properly by running the docker info command in your terminal. If Docker is running, the command will succeed. If Docker is not running, the docker info command will hang or return an error including the message "Cannot connect to the Docker daemon".

1. Create a new project

Create a new Sandbox SDK project:

npmyarnpnpm

npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal#v0

yarn create cloudflare my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal#v0

pnpm create cloudflare@latest my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal#v0

This creates a my-sandbox directory with everything you need:

  • src/index.ts - Worker with sandbox integration
  • wrangler.jsonc - Configuration for Workers and Containers
  • Dockerfile - Container environment definition
cd my-sandbox

2. Explore the template

The template provides a minimal Worker that demonstrates core sandbox capabilities:

import { getSandbox, proxyToSandbox, 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> {
        const url = new URL(request.url);

        // Get or create a sandbox instance. For user-facing apps,
        // derive this ID from the authenticated user.
        const sandbox = getSandbox(env.Sandbox, "my-sandbox");

        // Execute Python code
        if (url.pathname === "/run") {
            const result = await sandbox.exec('python3 -c "print(2 + 2)"');
            return Response.json({
                output: result.stdout,
                error: result.stderr,
                exitCode: result.exitCode,
                success: result.success,
            });
        }

        // Work with files
        if (url.pathname === "/file") {
            await sandbox.writeFile("/workspace/hello.txt", "Hello, Sandbox!");
            const file = await sandbox.readFile("/workspace/hello.txt");
            return Response.json({
                content: file.content,
            });
        }

        return new Response("Try /run or /file");
    },
};

Key concepts:

  • getSandbox() - Gets or creates a sandbox instance by ID. Use a stable ID to reconnect to the same sandbox. In user-facing apps, scope IDs to a single user.
  • sandbox.exec() - Execute shell commands in the sandbox and capture stdout, stderr, and exit codes.
  • sandbox.writeFile() / readFile() - Write and read files in the sandbox filesystem.

3. Test locally

Start the development server:

npm run dev
# If you expect to have multiple sandbox instances, you can increase `max_instances`.

Note

First run builds the Docker container (2-3 minutes). Subsequent runs are much faster due to caching.

Test the endpoints:

# Execute Python code
curl http://localhost:8787/run

# File operations
curl http://localhost:8787/file

You should see JSON responses with the command output and file contents.

4. Deploy to production

Deploy your Worker and container:

npx wrangler deploy

This will:

  1. Build your container image using Docker
  2. Push it to Cloudflare's Container Registry
  3. Deploy your Worker globally

Wait for provisioning

After the first deployment, wait several minutes before you expect sandbox requests to succeed. The Worker deploys immediately, but the container image still has to provision.

Check deployment status:

npx wrangler containers list

5. Test your deployment

Visit your Worker URL (shown in deploy output):

# Replace with your actual URL
curl https://my-sandbox.YOUR_SUBDOMAIN.workers.dev/run

Your sandbox is now deployed and can execute code in isolated containers.

Understanding the configuration

Your wrangler.jsonc connects three pieces together:

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

[[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"

For detailed configuration options including environment variables, secrets, and custom images, see the Wrangler configuration reference.

Next steps

Now that you have a working sandbox, explore more capabilities:

Was this helpful?

YesNo

On this page

Getting started (13) - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/sandbox/sdk/get-started/#page","headline":"Getting started","description":"Create your first Sandbox SDK 0.x Worker to execute Python code in isolated containers.","url":"https://developers.cloudflare.com/sandbox/sdk/get-started/","inLanguage":"en","image":"https://developers.cloudflare.com/sandbox/sdk/get-started/og.png?v=00c05b54db8459dc","dateModified":"2026-09-30","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: Practical guides for solving specific tasks with the Sandbox SDK 0.x. title: How-to guides image: https://developers.cloudflare.com/sandbox/sdk/guides/og.png?v=1c45ebe13abdbb9d

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.