Sandbox SDK 1.0: What Cloudflare Changed for Code Execution

Cloudflare released Sandbox SDK 1.0 on September 30, moving control of each sandbox container from the SDK into the developer's own Durable Object class. That changes more than the API surface: developers can now decide when a container starts and stops, which image it uses, what network access it receives, and how application code exposes sandbox capabilities. The release also gives existing 0.x users a defined migration path, with security and bug fixes for the old SDK scheduled through the end of 2026.

Sandbox SDK 1.0 puts the container under your Durable Object

In the previous Sandbox SDK architecture, the package's Sandbox class handled much of the container lifecycle and routed requests through a service running inside the sandbox. In version 1.0, developers write the Durable Object class themselves and access the container directly through this.ctx.container. A Durable Object is Cloudflare's stateful server-side execution model, so this change places decisions about a sandbox's lifetime and behavior alongside the application's own state and logic. The @cloudflare/sandbox package now provides smaller helpers, including file-transfer functionality, while the container API handles the core execution model.

Sandbox SDK 1.0 changes what developers control

The practical difference is that a single Durable Object class can start sandboxes with different images and instance sizes instead of treating those choices as fixed SDK behavior. The class can also decide when a sandbox should stop, whether it should have Internet access, and what happens after a command finishes or a user becomes idle. Commands can run with streamed input and output, receive signals, and expose terminals, while ports inside the sandbox can be turned into authenticated previews. This makes the SDK less of a predefined execution service and more of a programming layer that lets an application define its own sandbox lifecycle.

The biggest improvement is control over sandbox lifetime

Short-lived code execution and long-running development environments have different needs, and version 1.0 lets the application make that distinction. A build job can start a container, execute its commands, return the result, and stop the sandbox when the work is complete, while an interactive environment can keep running until the user goes idle. Cloudflare also supports snapshots in public beta, allowing the files of a sandbox to be saved and used to start the same environment or a new one later. The result is a lifecycle that can be tied to an actual task rather than a fixed timeout built into an SDK abstraction.

Prepared images make the startup change measurable

Cloudflare's migration documentation reports that Sandbox SDK 1.0 can start prepared images with a median time from start() to the first command of under 600 milliseconds, compared with about 4 seconds on version 0.x. Those figures come from Cloudflare's own documentation rather than an independent benchmark, so they describe the platform's reported behavior rather than a universal performance result. The important programming consequence is that the difference is large enough to matter for workloads that repeatedly create short-lived environments: a startup measured in hundreds of milliseconds can fit inside an interactive workflow much more easily than one measured in several seconds.

The new model also changes how networking and credentials are handled

A sandbox should not automatically receive everything available to the Worker that created it, particularly when it is executing generated or otherwise untrusted code. In version 1.0, the Worker can control outbound requests for individual hostnames, while credentials and Cloudflare bindings remain in Worker code rather than being copied into the sandbox. Cloudflare's security documentation still warns that code running inside one sandbox can use everything reachable from that sandbox, including files, credentials, and network access that the application deliberately provides. The isolation boundary therefore reduces what the sandbox can reach from the surrounding application, but it does not make arbitrary code safe after sensitive resources have already been exposed to it.

Existing Sandbox SDK 0.x apps are not being cut off immediately

Cloudflare is not requiring every existing application to migrate immediately. Sandbox SDK 0.x remains available on npm and receives bug and security fixes through December 31, 2026, although it will not receive new features. Developers can migrate an application by replacing the old Sandbox class with a Durable Object class that controls this.ctx.container, then moving individual features such as terminals, previews, backups, and background processes to their 1.0 equivalents. Cloudflare also documents a side-by-side migration where a 0.x class and a 1.0 class can temporarily run in the same Worker, allowing sandboxes to move individually rather than all at once.

The migration has one detail developers should test before deployment

Moving to 1.0 is not a completely reversible configuration switch. Cloudflare's migration guide says the deployment that moves an existing sandbox class to the new policy is one-way, which is why it recommends rehearsing the change before production. A side-by-side migration can reduce that risk, but the application still needs to account for differences in how files, commands, environment variables, previews, and other 0.x features are represented. This is especially relevant for long-running sandboxes because an in-place migration can end commands running in 0.x containers, and some workspace-transfer paths have a 32 MiB message limit.

What Sandbox SDK 1.0 is actually useful for

The SDK is aimed at applications that need to execute code outside their main Worker process, including AI agents, development previews, data-analysis jobs, build pipelines, and user-supplied applications. A container provides a Linux environment with runtimes, packages, files, and processes, while the Worker remains responsible for deciding what the sandbox can access. That distinction makes the model useful for applications where code execution is part of the product rather than merely an internal deployment detail.

The real shift is from SDK-managed execution to application-managed execution

Sandbox SDK 1.0 is therefore less about adding another command API and more about changing who owns the execution model. Cloudflare has moved the important decisions into application code: which container to start, how long it should live, what it can reach, how its files persist, and which operations callers are allowed to perform. That gives developers more control, but it also means more responsibility for lifecycle handling, security boundaries, retries, and migration behavior. For teams already using Sandbox SDK 0.x, the useful next step is to map each feature they depend on to its 1.0 replacement before making the one-way production switch, while new projects can design around the Durable Object and container model from the beginning.