Cloudflare Releases Sandbox SDK 1.0 for Durable Objects

AIDeveloper44 Team

Overview of Sandbox SDK 1.0

Cloudflare has officially released version 1.0 of its Sandbox SDK, a significant update for developers building on the Workers platform. This release empowers developers to manage sandbox containers directly from within their Durable Objects by utilizing the new this.ctx.container API. By shifting control to the Durable Object layer, the SDK provides a more robust orchestration model for running untrusted or generated code in isolated Linux environments.

With the 1.0 release, developers can now exercise fine-grained control over the sandbox lifecycle. This includes the ability to select specific container images, define instance sizes for different tasks, and toggle network access on a per-sandbox basis. Because the control plane now resides within the Durable Object, developers can maintain stateful coordination for sandboxes, ensuring that tasks are handled with appropriate identity and capability scopes.

Key Features and Capabilities

The SDK introduces several functional improvements designed to streamline the operation of isolated environments:

• Direct Control API: Developers use this.ctx.container to start and monitor sandboxes. This removes the need for indirect management and allows for more complex interactions, such as managing long-running background processes.
• Container Snapshots: Currently in public beta, snapshots allow developers to save the state of a sandbox's writable root filesystem. This enables quick restoration of environments, which is particularly useful for iterative tasks or agents that need to resume work from a known baseline.
• Enhanced Terminal and Stream Access: The 1.0 release provides improved methods for streaming input and output from commands, sending signals to processes, and attaching terminal sessions, facilitating real-time interaction with the sandbox environment.
• Custom Hostnames and Auth: Applications can now serve previews from ports within the sandbox using custom hostnames and built-in authentication mechanisms, keeping the security boundary within the Worker code.

Integration and Migration

The shift to the 1.0 SDK represents a fundamental change in how sandboxes are managed on Cloudflare. Unlike the 0.x versions, which were managed through different mechanisms, the 1.0 architecture is designed to integrate deeply with the Durable Object scheduling policy, which is also in public beta.

For existing users, Cloudflare has emphasized that 0.x applications will continue to function. The previous SDK version will remain available on npm, and the company has committed to providing bug and security fixes through December 31, 2026. To assist in the transition, Cloudflare has published a comprehensive migration guide. This guide covers how to map 0.x features—such as background processes, tunnels, and preview URLs—to their 1.0 counterparts. The migration can be performed incrementally, allowing developers to run 1.0 classes alongside legacy 0.x classes while transitioning sandboxes one at a time.

Platform Context

Cloudflare’s sandbox environments are categorized into two primary types: containers and Dynamic Workers. While containers offer a full Linux environment suitable for running arbitrary binaries and long-running processes, Dynamic Workers provide a lightweight, isolated runtime for JavaScript, Python, or WebAssembly. The new Sandbox SDK 1.0 focuses primarily on the container runtime, providing the necessary tools to handle more intensive compute tasks that require a persistent Linux environment. As developers continue to build increasingly complex AI agents and automated testing pipelines, these tools offer the level of control necessary to manage these environments securely and efficiently.

Enjoyed this?

Get more posts like this delivered to your inbox.

Subscribe