@cloudflare/sandbox
1.0.3 · 22 Oct 2026Apache-2.02.1M / weekRepositoryHomepagenpmAtom feed
0.12.14 is the newest release of 0.8.x.
In short
2 new4 fixed
Release note
Patch Changes
Avoid duplicate session-create calls when parallel operations hit a
fresh sandbox. Parallel callers now share one setup call instead of
each issuing their own. Sequential operations are unaffected.Session setup also now retries cleanly on the next operation if it is
interrupted partway through — including by a container stop during
first use — instead of leaving the sandbox in a state that looks
initialized but references a session the container no longer has.Fix sandboxes staying alive past their configured
sleepAftervalue.Workers that passed configuration options to
getSandbox()on every request (sleepAfter,keepAlive, orcontainerTimeouts) could unintentionally extend sandbox lifetimes. The SDK's internal reapply path treated identical reapplied values as activity, resetting the sleep timer each time. Under sustained traffic, sandboxes would never sleep at all.After updating, reapplying the same configuration value is a true no-op. Your
getSandbox()calls continue to work exactly as before; sandboxes now respect their configured sleep timers regardless of how often configuration is reapplied.This release also removes the unused
baseUrloption fromSandboxOptions, along with thesetBaseUrlRPC method on the Sandbox Durable Object. The option had no effect on runtime behavior; preview URLs are driven by thehostnamepassed to preview-URL APIs. If you were settingbaseUrlongetSandbox(), you can safely remove it. Directly invoking the undocumentedsetBaseUrlRPC method will now error.Improve reliability of
desktop.stop()as well as general isolation of the desktop processes by
running them in a subprocess. This should ensure that processes are cleaned up when callingdesktop.stop()and crashes should not impact the sandbox container service.Fix stream controller race condition causing "Invalid state: Controller is already closed" errors
Resolves an issue where client disconnections during streaming operations could cause unhandled TypeError exceptions, potentially corrupting the SDK bridge state. The fix adds defensive error handling in the execute streaming handler to gracefully handle callbacks firing after stream cancellation.
Adds a new
transport: 'http' | 'websocket'field to thegetSandbox()options. This can be
used to dynamically select transport on a per-sandbox basis.Note
Changing transport on an already existing sandbox may result in dropped connections, it is
recommended to keep the same transport for the lifetime of the sandbox instance.const sandbox = getSandbox(env.Sandbox, 'my-sandbox', { transport: 'websocket' });Adds support for local backup and restore through the
BACKUP_BUCKETR2 binding in local development whenlocalBucket: trueis set.
A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.