Cloudflare Sandbox SDK 1.0 shipped on September 30, 2026, and it changes who controls a sandbox: your own Durable Object class now starts, stops, and snapshots each sandbox container directly through the Durable Object container API on this.ctx.container. This article covers what is new in 1.0, a working TypeScript example, the helper classes that ship with @cloudflare/sandbox, and the migration path from 0.x, which receives fixes until December 31, 2026.
- What Changed in Sandbox SDK 1.0
- A Minimal 1.0 Sandbox in TypeScript
- Helper Classes: Files, S3Mount, and DirectoryBackup
- Migrating from Sandbox SDK 0.x
What Changed in Sandbox SDK 1.0
In 1.0, your Durable Object class talks to the container API directly instead of going through a managed abstraction. According to Cloudflare's changelog, your class can now:
- Choose the image and instance size each time it starts a sandbox. One class can run sandboxes on different images, and a deploy does not restart sandboxes that are already running.
- Save a sandbox's files as a snapshot, now in public beta, and start the same sandbox or a new one from that snapshot.
- Decide when each sandbox stops: when a task finishes, when its user goes idle, or after it saves a snapshot.
- Run commands with streamed input and output, send them signals, and open terminals.
- Serve previews from ports in the sandbox, with your own hostnames and authentication.
- Handle outbound requests for each hostname in Worker code, so credentials and bindings stay in your Worker and out of the sandbox.
- Expose only the methods you want callers to use, and run an agent in the same Durable Object with a model tool that executes commands in the sandbox.
The class uses the container API with the durable_object scheduling policy and container snapshots, both currently in public beta.
A Minimal 1.0 Sandbox in TypeScript
Cloudflare's changelog example shows the shape of a 1.0 sandbox class. The Durable Object owns the container, writes a script into it, and runs it:
import { Files } from "@cloudflare/sandbox";
import { DurableObject } from "cloudflare:workers";
export class MySandbox extends DurableObject<Env> {
private readonly container: Container;
private readonly files: Files;
constructor(ctx: DurableObjectState, env: Env) {
super(ctx, env);
if (!ctx.container) {
throw new Error("No container is configured");
}
this.container = ctx.container;
this.files = new Files(ctx.container);
}
async run(script: string) {
if (!this.container.running) {
// Your code chooses the image, size, and network access.
this.container.start({
image: this.container.images.sandbox,
instance: "lite",
enableInternet: false,
});
}
await this.files.writeFile("/tmp/task.sh", script);
const proc = await this.container.exec(["sh", "/tmp/task.sh"]);
return proc.output();
}
}Two details are worth noting. The sandbox starts lazily, only when run is called and the container is not already running. And enableInternet: false cuts off network access at start time, which is the right default for executing untrusted code. For local or self-hosted approaches to the same problem, see our guide on isolating untrusted code execution with rootless Docker and gVisor.
Helper Classes: Files, S3Mount, and DirectoryBackup
The raw container API is deliberately small, so @cloudflare/sandbox adds classes for the work it does not include:
- Files streams files in and out of the running sandbox.
- S3Mount mounts an S3-compatible bucket, such as R2. Your Worker signs each storage request, so credentials stay out of the sandbox.
- DirectoryBackup saves a directory to R2 and restores it into any sandbox, including one running a newer image.
Migrating from Sandbox SDK 0.x
Existing 0.x applications keep running, and @cloudflare/sandbox 0.x stays on npm. Cloudflare will ship bug and security fixes for 0.x until December 31, 2026, and the 0.x documentation remains available.
Cloudflare's migration guide shows the 1.0 code for each 0.x feature, including preview URLs, tunnels, background processes, terminals, backups, and the code interpreter, and it keeps the preview URLs and named tunnels your 0.x application created working. You can move every sandbox in one deploy, or run a 1.0 class next to your 0.x class and migrate sandboxes one at a time. One caveat: the deploy that moves an existing class to the new scheduling policy is one-way, so rehearse it first.