JA EN
shiichan

Sandbox SDK 1.0 Preview Is Here! Say Goodbye to Session Management and Transport Selection

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

Hi, I'm Shii-chan! Cloudflare just dropped a pretty big update about the Sandbox SDK. I peeked inside and it's gotten so much lighter — I got excited just reading through it!

Cloudflare Changelog developers.cloudflare.com

What was announced?

Cloudflare's Changelog announced that Sandbox SDK 1.0 is now available to preview under the npm @next tag. Existing applications can keep using the current stable 0.12.x line, so you don't have to switch over right away.

Sandbox SDK originally shipped as a feature-rich library for running untrusted and agent-driven work on Cloudflare Containers. Now that both Sandbox and Containers have matured, this preview is a thinner SDK built on top of a richer Cloudflare Containers foundation.

The story so far

The existing Sandbox SDK had quite a bit built in:

  • "Session execution," which carried shell state forward between runs
  • Transport selection via SANDBOX_TRANSPORT, the transport option on getSandbox(), and setTransport()
  • PTY and terminal operations that went through older, session-shaped helpers
  • A code interpreter baked into the SDK, which you couldn't opt out of even if you didn't need it

All of that was useful, but it also meant the SDK itself had grown more complex over time.

What changes

The 1.0 preview cleans a lot of that up:

  • A single execution interface, sandbox.exec(). Pass it an argument list and it returns as soon as the process starts, giving you a handle for output, logs, waits, and signals. Short commands and long-running services now share the same API
  • Session execution is gone. Each launch is independent and doesn't carry shell state forward. Pass cwd and env when you need them, or fold multi-step shell logic into one explicit shell command
  • RPC is now the only transport. SANDBOX_TRANSPORT, transport, and setTransport() are no longer needed
  • PTY and terminal handling moves to a simpler interface built around createTerminal / connect, instead of the old session-shaped helpers
  • The code interpreter is now an extension you configure on your Sandbox subclass, so you only ship what you actually use

Cloudflare recommends starting new projects on @next and migrating existing apps once you're ready, so you're set for when 1.0 goes stable. The Worker package and container image need to be deployed from the same @next line.

Dive Deep

Installing it is straightforward via npm:

npm i @cloudflare/sandbox@next

yarn, pnpm, and bun all work the same way with their respective add commands.

For coding agents, there's also a Cloudflare Skills package, meant to be picked based on what you're doing:

  • sandbox-next — for the @next line (recommended for new projects)
  • sandbox-stable — for the current stable package
  • sandbox-migrate-to-next — when you're ready to migrate from stable to @next

For cleaning up deprecated APIs on the stable package, there's a separate 2026 deprecation guide.

One thing to note: the self-deployed Sandbox bridge isn't part of this preview yet. Cloudflare says they're working on bringing it in line with the latest code, and in the meantime you should use the stable bridge together with the matching stable package and container image.

As for when 1.0 goes fully stable, Cloudflare's explanation is that further Cloudflare Containers features will let them keep shrinking the Sandbox SDK further, and they plan to ship 1.0 once those land — no firm date yet. Until then, the @next preview will keep being supported and maintained alongside the current stable release.

Wrap-up

Here's the gist of this announcement:

  • Sandbox SDK 1.0 is now previewable via the npm @next tag, while the stable line stays on 0.12.x
  • The main changes are unifying around sandbox.exec(), dropping session execution, moving to RPC-only transport, reworking PTY/terminal handling, and turning the code interpreter into an extension
  • The self-deployed bridge isn't supported yet, and there's no confirmed date for the full 1.0 release

If you're already running agents or untrusted code on Cloudflare Containers — or thinking about starting — this is an update worth keeping an eye on.

Related posts