Packages

@cloudflare/sandbox

1.0.3 · 22 Oct 2026Apache-2.02.1M / weekRepositoryHomepagenpmAtom feed

Your version

0.8.14

24 Apr 2026Where it was published

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 sleepAfter value.

    Workers that passed configuration options to getSandbox() on every request (sleepAfter, keepAlive, or containerTimeouts) 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 baseUrl option from SandboxOptions, along with the setBaseUrl RPC method on the Sandbox Durable Object. The option had no effect on runtime behavior; preview URLs are driven by the hostname passed to preview-URL APIs. If you were setting baseUrl on getSandbox(), you can safely remove it. Directly invoking the undocumented setBaseUrl RPC 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 calling
    desktop.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 the getSandbox() 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_BUCKET R2 binding in local development when localBucket: true is 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.