Overview
The Cloudflare Sandbox SDK lets you run untrusted or AI-generated code inside an isolated Linux environment that belongs to a single user, task, or session. It is a natural fit for coding agents, code interpreters, online IDEs, and CI-style jobs that need a real shell rather than a JavaScript isolate.
A sandbox is a Durable Object plus the Container it starts. Your Worker stays in control: it decides who gets a sandbox, which hosts that sandbox may reach, and which credentials never enter it.
What the SDK Adds
On top of the Containers API, @cloudflare/sandbox provides:
- Files — stream files in and out of the running instance, with familiar Linux errors such as
ENOENT - S3Mount — mount an S3-compatible bucket at a path; the Worker signs every storage request, so credentials stay outside the sandbox
- DirectoryBackup — save a directory to R2 and restore it into any container, even one running a newer image
What You Can Build
- Run a script and read its output
- Keep a dev server or long build running in the background
- Open an interactive terminal in the browser
- Process files from an R2 bucket
- Save a workspace and resume it later
- Preview a web app while you edit it, including on its own hostname
- Restrict which network hosts a sandbox can reach
- Run a coding agent against a repository
Getting Started
Create a project from the minimal template:
npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimalThe template gives each name in the URL its own sandbox. Your Durable Object starts the container on demand, writes a script with Files, executes it, and returns the output — and the Worker picks the right sandbox for each user with env.SANDBOX.getByName(...). The Worker needs the nodejs_compat flag, and the container image must include the helper used by Files.
If you only need to run JavaScript or Python without a full Linux environment, Cloudflare’s Dynamic Workers are a lighter option.
Upgrading from 0.x
Version 1.0 moved container ownership into your own Durable Object; the package now focuses on file operations, bucket mounts, and backups. An official migration guide maps every 0.x API to its replacement.
Use Cases
- AI coding agents that need to clone repos, install packages, and run tests
- Online code playgrounds and interpreters
- Per-user build or data-processing jobs with strict network egress control