JA EN
shiichan

Sandbox SDK 1.0 Is Here: Control Every Sandbox from Your Own Durable Object

Cloudflare Changelog ★★★ View Markdown
#cloudflare#ai#serverless

Hi everyone, it's Shii-chan! Today's news is Sandbox SDK 1.0, and I'm really excited about it.

Cloudflare Changelog developers.cloudflare.com

What was announced?

In the Cloudflare Changelog, Sandbox SDK 1.0 was released. Your own Durable Object class can now control each sandbox container directly through the Durable Object container API on this.ctx.container.

Here is what 1.0 lets your class do:

  • Choose the image and instance size each time a sandbox starts (one class can run different images, and a deploy does not restart running sandboxes)
  • Save a sandbox's files as a snapshot (public beta) and start the same or a new sandbox from it
  • Decide when each sandbox stops, for example when a task finishes, when the user goes idle, or after a snapshot
  • Run commands with streamed input and output, send signals, and open terminals
  • Serve previews from ports in the sandbox, with your own hostnames and authentication
  • Handle outbound requests per hostname in Worker code, so credentials and bindings stay in your Worker
  • Expose only the methods you want callers to use
  • Run an agent in the same Durable Object and give the model a tool that runs commands in the sandbox

The story so far

Until now you used the 0.x SDK, where the sandbox class followed a shape provided by the SDK. In 1.0 the SDK is positioned as a set of utilities you pick from, not a base class.

What changes

Control moves to your own Durable Object. That makes it easier to switch images and sizes per task and to decide stop timing in your app logic. If you build agent infrastructure, this is a big one.

Dive Deep

  • Helper classes Files, S3Mount, and DirectoryBackup come from the @cloudflare/sandbox package
  • It uses the durable_object scheduling policy (public beta), and snapshots also require a public beta feature
  • 0.x gets bug and security fixes until 2026-12-31, and existing 0.x apps keep running
  • You can move all sandboxes at once or migrate gradually alongside 0.x classes
  • Moving an existing class to the new policy is permanent, so a rehearsal is recommended
  • A migration guide covers 1.0 equivalents for preview URLs, tunnels, background processes, terminals, and backups

Wrap-up

  • Durable Objects can control sandboxes directly via ctx.container
  • Per-start image and size choice, snapshots (beta), and stop-timing control are available
  • 0.x is supported until 2026-12-31, and migrating to the new policy is one-way

This is for anyone who wants fine-grained control over their own agent sandboxes!

Related posts