The Sandbox SDK has moved to version 1.0, exposing the container API directly on this.ctx.container inside a Durable Object. This change lets engineers treat each sandbox as a first‑class resource that can be started, stopped, and configured from the same DO that handles request routing.
Durable Object‑Based Sandbox Control
With SDK 1.0 a single Durable Object class can launch multiple sandboxes, each with its own image and instance size. The launch does not force a restart of any already‑running sandbox, so deployments can proceed without disrupting active sessions. The API also supports creating a snapshot of a sandbox’s file system (currently in public beta) and restoring from that snapshot to recreate the same environment or spin up a fresh one.
export class MySandbox extends DurableObject {
constructor(ctx, env) {
super(ctx, env);
if (!ctx.container) throw new Error("No container is configured");
this.container = ctx.container;
}
async run(script) {
if (!this.container.running) {
// image, size, and network are chosen here
this.container.start({ image: "my-image", size: "medium" });
}
// further command execution omitted for brevity
}
}
Operational Shifts
Because the DO now owns the sandbox lifecycle, engineers can embed termination logic directly in the object – for example, stopping a sandbox when a user becomes idle or after a snapshot is taken. This gives finer‑grained cost control and reduces the need for external cron jobs. Streaming command I/O and terminal access are also routed through the DO, simplifying monitoring and logging pipelines.
Previews can be served from sandbox ports using custom hostnames and authentication handled in the Worker layer. Outbound requests from those hostnames are intercepted by the DO, allowing credentials and bindings to stay within the Worker context rather than being exposed inside the container.
Security and Surface‑Area Considerations
Exposing only the methods you intend callers to use limits the attack surface of the DO. However, the ability to run arbitrary commands, open terminals, and forward ports means that any misconfiguration could inadvertently grant broader access. Practitioners should audit the method whitelist and ensure that credential handling in outbound request hooks does not leak secrets into the sandbox.
The snapshot feature, while useful for state persistence, is still in public beta. Teams should treat snapshot storage as a mutable artifact and consider versioning or integrity checks if the data is security‑sensitive.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
Engineers can now consolidate sandbox orchestration, credential management, and preview serving inside a single Durable Object, reducing architectural sprawl. The immediate actions are to refactor existing sandbox launch code to use this.ctx.container, define clear start‑stop policies, and audit exposed methods for least‑privilege access. Keep an eye on the snapshot beta for stability and plan for any required migration if the API evolves.