@cloudflare/sandbox
1.0.3 · 22 Oct 2026Apache-2.02.1M / weekRepositoryHomepagenpmAtom feed
123 stable releases, newest first, by release line. Notes are quoted as the maintainers published them.
- 1.x · latest line
1.0.3
22 Oct 2026Fix
Files.readDirectory()dropping a leading U+FEFF from entry names. Names that start with U+FEFF now come back unchanged, so passing them tostat()or other file operations finds the entry.
1.0.2
20 Oct 2026Fix
Files.readFile()hanging forever when the container sends file bytes before the opening control frame. The read now completes however the container transport orders the two streams.
1.0.1
13 Oct 2026Pin Zod 4.6.5, the version that Workers tooling such as
@cloudflare/vitest-pluginpins, so a project that installs both installs one copy of Zod instead of two.
1.0.0
30 Sep 20261.0.0 is a ground-up rewrite. Your Durable Object extends
DurableObjectand runs its container through the nativectx.containerAPI. The package addsFiles,S3MountandDirectoryBackupfor the work the platform doesn't do itself. Application images copy thesandbox-shimhelper fromdocker.io/cloudflare/sandbox:1.0.0.Major Changes
1.0.0 is a ground-up rewrite. Your Durable Object extends
DurableObjectand runs its container through the nativectx.containerAPI. The package addsFiles,S3MountandDirectoryBackupfor the work the platform doesn't do itself. Application images copy thesandbox-shimhelper fromdocker.io/cloudflare/sandbox:1.0.0.Moving from 0.12 is a migration, not a version bump. See Migrate from 0.x. The Sandbox docs and the API reference cover 1.x.
- 0.12.x
0.12.14
22 Oct 2026- Security
Update the container runtime to Bun 1.4.4. Bun checks certificates against its own built-in CA list, and in 1.4.4 that list no longer trusts the compromised eMudhra intermediates, so the
buncommand andcreateBackup()uploads of 10 MiB or more now reject their certificates. Bun 1.4.4 also updates Brotli to 1.2.1, which fixes CVE-2026-111497. The-opencodeimage ships OpenCode 1.19.4 or later, which also runs on Bun 1.4.4.
0.12.13
21 Oct 2026Stop trusting certificates from the compromised eMudhra intermediate CAs in the container images. The images now ship the updated Ubuntu and Alpine CA bundles, Node.js 22.23.4, cloudflared 2026.10.2, and pip 26.2.2 in the
-pythonimage. Bun keeps trusting these certificates until it releases a fix, which affectsbun, opencode, and multipart uploads increateBackup()for archives of 10 MiB or more. Update the container image to get this fix. See the eMudhra certificate compromise for details.
0.12.12
20 Oct 2026Fix
mountBucket()breaking an existing mount when a second call for the same mount path fails with "already in use". The existing mount now stays mounted and usable.Keep streaming
exec()alive while a command is quiet, and enforce itstimeout. Quiet commands were cut off after about four minutes on the HTTP transport and five on WebSocket. The timeout was ignored on those transports, and on every transport for commands that run in a session. Requires the matching container image.Keep R2 binding and credential-proxy bucket mounts working when the Sandbox Durable Object restarts while its container keeps running. The mounts used to stay listed but fail every read and write with
EIOuntilmountBucket()was called again.
Patch Changes
Fix
mountBucket()breaking an existing mount when a second call for the same mount path fails with "already in use". The existing mount now stays mounted and usable.Keep streaming
exec()alive while a command is quiet, and enforce itstimeout. Quiet commands were cut off after about four minutes on the HTTP transport and five on WebSocket. The timeout was ignored on those transports, and on every transport for commands that run in a session. Requires the matching container image.Keep R2 binding and credential-proxy bucket mounts working when the Sandbox Durable Object restarts while its container keeps running. The mounts used to stay listed but fail every read and write with
EIOuntilmountBucket()was called again.Fix
createOpencodeServer()andcreateOpencode()waiting for the full three-minute startup timeout whenOPENCODE_SERVER_PASSWORDis set. When the password is passed inenv, the client returned bycreateOpencode()now authenticates with it.Create the s3fs password file for
mountBucket()with mode 0600 from the start. The file used to be readable by other users in the container until a chmod a moment later, long enough for a non-root process to open it and read the bucket credentials. Upgrade the container image together with the SDK to close the gap; with an older image, mounts work as before.Answer a preview request with
502when the app's port in the container fails, for example because nothing listens on it or it closes the connection, and log the original error. Previously the error escaped the Sandbox,proxyToSandbox()answered500 Proxy routing error, and the log blamed a platform runtime update.Forward WebSocket upgrades on preview URLs with
Host: localhost:<port>, like every other preview request. Dev servers that check theHostheader, such as Vite, no longer reject HMR connections. The public hostname is still inX-Forwarded-Host.Keep preview URLs and tunnels working on the RPC transport after the control connection reconnects. The connection closes after 1 second without calls, and the next call used to rerun the sandbox's start handling even though the container was still running. Preview URLs then returned
410 STALE_PREVIEW_URL,getExposedPorts()returned an empty list, quick tunnels disappeared fromtunnels.list(), andtunnels.get()could fail with "Tunnel recovery attempts were exhausted".Stop the first call on the RPC transport from failing when Cloudflare can't provide a container right away. The call now keeps waiting for the container within its retry window.
Stop the container server from crashing with
ENOENT: no such file or directory, watch '…/<id>.log.stderr'while commands run. The crash killed every process in the container. Update the container image to pick up this fix.tunnels.get()on the RPC transport now reports the real tunnel error, such ascloudflaredfailing to start or missing from the image, instead of "Tunnel recovery attempts were exhausted". It also no longer leaves a port stuck after giving up: acloudflaredleft running from an earlier attempt is stopped and replaced. Replacing it needs the matching container image.
0.12.11
19 Oct 2026Stop backups from dropping whole directories when
excludesorgitignore: truematch a nested path. For example,excludes: ['.cache/foo/*/node_modules']no longer removes all of.cachefrom the archive. A multi-component pattern such asbuild/outputnow matches only relative to the backup directory, while a single-component pattern such asnode_modulesstill matches at any depth. Because mksquashfs does not support**, a pattern like**/node_modules/.cachenow excludes onlynode_modules/.cacheat the root of the backup directory; add a pattern for each nested location that must stay out of the backup.Return 404 with
workspace_read_not_foundfrom the bridge'sGET /v1/sandbox/:id/file/*when the file doesn't exist. The route used to return 200 with an empty body, the same response as an empty file.Fix local bucket mounts for large files and write bursts. On the RPC transport, objects over 4 MiB now stream into the container instead of failing with an interrupted runtime connection. Container files stream back to R2 byte for byte, without loading the whole file into Worker memory. A file being written uploads once its changes settle, instead of on every write.
Patch Changes
Stop backups from dropping whole directories when
excludesorgitignore: truematch a nested path. For example,excludes: ['.cache/foo/*/node_modules']no longer removes all of.cachefrom the archive. A multi-component pattern such asbuild/outputnow matches only relative to the backup directory, while a single-component pattern such asnode_modulesstill matches at any depth. Because mksquashfs does not support**, a pattern like**/node_modules/.cachenow excludes onlynode_modules/.cacheat the root of the backup directory; add a pattern for each nested location that must stay out of the backup.Return 404 with
workspace_read_not_foundfrom the bridge'sGET /v1/sandbox/:id/file/*when the file doesn't exist. The route used to return 200 with an empty body, the same response as an empty file.Fix local bucket mounts for large files and write bursts. On the RPC transport, objects over 4 MiB now stream into the container instead of failing with an interrupted runtime connection. Container files stream back to R2 byte for byte, without loading the whole file into Worker memory. A file being written uploads once its changes settle, instead of on every write.
Stop writing command text and output to Sandbox logs. Exec and process log events now record IDs, exit codes, durations, and output lengths, and the OpenAI Agents
ShellandEditoradapters no longer log commands, stderr, or patch text, so secrets in commands, output, or patches no longer reach Workers Logs or container logs. Command failure messages no longer repeat the command; it remains available on the error'scontext.command.Fix
restoreBackup()error reporting for archives of 10 MB or more. A failed download part now throws aBackupRestoreErrorthat includes curl's error output and each part's exit code, instead of aShell terminated unexpectedlysession error.Sync local bucket mounts outside
/workspace, such as/data, from the container back to R2.watch()andcheckChanges()now accept any absolute path on every transport, as documented. A local mount whose container rejects the watch now logs one error instead of retrying forever.
0.12.10
23 Sep 2026Allow multipart backup uploads to trust the runtime HTTPS interception certificate, so backups larger than 10 MiB work when
interceptHttpsis enabled.Reject bucket-level mutations sent through
credentialProxymounts while preserving object writes, bucket probes, and scoped listings.Fix
File existserrors when git or other tools recreate files in a directory restored withrestoreBackup(), such as runninggit reset --hardwhile a dev server watches the project.
0.12.9
27 Aug 2026Allow mounted R2 buckets to open object keys containing spaces, symbols, percent signs, and non-ASCII characters.
0.12.8
24 Aug 2026Enforce source mount prefixes for server-side copies between R2 bindings.
0.12.7
14 Aug 2026Ensure stable releases advance npm's
latesttag only after all release artifacts pass verification.
0.12.6
13 Aug 2026Enforce mounted bucket and prefix boundaries for server-side copy operations when using
credentialProxy.
0.12.5
7 Aug 2026Instrument the bridge API with Cloudflare custom spans. Each endpoint now emits
abridge.<operation>span annotated with the sandbox ID, container UUID, and
operation-specific metadata (command, file path, port, session ID, and so on),
so requests are traceable end to end. Enable tracing withobservability.traces.enabledin your Worker configuration.Make
destroy()succeed when the sandbox container was never admitted, so cleanup no longer fails with a no-instance platform error.Reduce intermittent startup failures during concurrent sandbox creation where operations could fail with a disposed RPC session error.
Instrument the bridge API with Cloudflare custom spans. Each endpoint now emits
abridge.<operation>span annotated with the sandbox ID, container UUID, and
operation-specific metadata (command, file path, port, session ID, and so on),
so requests are traceable end to end. Enable tracing withobservability.traces.enabledin your Worker configuration.Make
destroy()succeed when the sandbox container was never admitted, so cleanup no longer fails with a no-instance platform error.Reduce intermittent startup failures during concurrent sandbox creation where operations could fail with a disposed RPC session error.
Surface container capacity and admission failures as retryable
ContainerUnavailableErrorwith a structuredreason, including no-instance and max-instances cases. Callers can branch onerror.reasoninstead of parsing platform messages.Fill the warm pool in bounded-parallel batches instead of one container at a
time, so it primes and recovers far faster after a burst. Tune the batch size
withWARM_POOL_SCALE_BATCH_SIZE(default 5, clamped to 20).Refill the warm pool the moment it drains instead of waiting for the next
background tick. After a burst consumes warm containers, replenishment now
starts immediately, cutting the latency tail for sandboxes created during
sustained or back-to-back bursts.Let the warm pool know its instance ceiling up front via the
WARM_POOL_MAX_INSTANCESbridge variable. Set it to match your container'smax_instancesso the pool makes correct capacity decisions without first
crashing into the limit.0(the default) preserves the existing auto-learn
behaviour.
0.12.4
21 Jul 2026Add
labelstoSandboxOptionssogetSandbox()can attach Cloudflare Container labels for analytics and observability. Labels are applied on container start; updates while running apply on the next start.
0.12.3
1 Jul 2026Restoring a backup now survives a durable object restart.
Reduces startup failures when a sandbox is booting or being replaced during container deployment. As well as providing structured errors for sandbox runtime and platform interruptions including retry guidance for idempotent operations.
Recover quick tunnels when the sandbox runtime is replaced.
tunnels.get(port)now provisions through an idempotent runtime-run boundary so a retry after a replacement returns a currently usable URL instead of a dead one, andtunnels.list()no longer returns quick tunnel URLs known to be stale after a container restart.
0.12.2
25 Jun 2026Disable the default session for bridge command and file requests. Calls without
Session-Idnow run without reusing shell state; passSession-Idfrom the session API to preserve working directory or environment across calls.
0.12.1
9 Jun 2026Recover automatically from transient infrastructure failures when the SDK opens its WebSocket control connection to a sandbox. Previously, any 5xx response other than 503 on the upgrade would fail the SDK call even when the container was healthy.
0.12.0
8 Jun 2026- Removed
Remove the desktop client API and desktop Docker image variant. The
sandbox.desktopAPIs,DesktopClientexports, desktop-related types/errors, and-desktopcontainer image are no longer available. Add
credentialProxyoption tomountBucketto keep real S3 credentials out of the container. When enabled, the Durable Object intercepts and signs outbound S3 requests — the container only sees dummy credentials. Supports S3-compatible endpoints, R2, and GCS HMAC signing, with optimized R2 mount defaults for reliable read and write performance.Fix bucket mounts when a Sandbox class defines a catch-all outbound handler by routing SDK-managed mount hosts through the SDK ContainerProxy.
Minor Changes
- Removed
Remove the desktop client API and desktop Docker image variant. The
sandbox.desktopAPIs,DesktopClientexports, desktop-related types/errors, and-desktopcontainer image are no longer available.
Patch Changes
Add
credentialProxyoption tomountBucketto keep real S3 credentials out of the container. When enabled, the Durable Object intercepts and signs outbound S3 requests — the container only sees dummy credentials. Supports S3-compatible endpoints, R2, and GCS HMAC signing, with optimized R2 mount defaults for reliable read and write performance.Fix bucket mounts when a Sandbox class defines a catch-all outbound handler by routing SDK-managed mount hosts through the SDK ContainerProxy.
Fix phantom
runningprocesses after a failedstartProcesscall. When the underlying session was unavailable or threw during startup, the process record was left in memory with statusrunningand would appear inlistProcesses()indefinitely. Failed startups are now correctly marked as terminalerrorrecords.
- 0.11.x
0.11.0
1 Jun 2026Prevent stale preview URLs from waking or reaching sandbox runtimes. Invalid, revoked, or destroyed preview URLs return
404 INVALID_TOKEN; authorized URLs that are not activated for the current runtime return410 STALE_PREVIEW_URLuntil the port is exposed again. Existing preview URLs that previously survived container restart now return410 STALE_PREVIEW_URLafter a restart until the port is exposed again in the new runtime.getExposedPorts()andisPortExposed()now report only ports that are currently preview-forwardable in the active runtime.unexposePort()is now idempotent: revoking a port that is not currently exposed succeeds without contacting the container. Preview URL state no longer uses the container-local exposed-port registry or proxy routes.Allow backup and restore presigned URLs to target non-default R2 endpoints. Set
BACKUP_BUCKET_ENDPOINT, for examplehttps://<account_id>.eu.r2.cloudflarestorage.com, when your backup bucket uses an R2 jurisdiction.Add bridge endpoints for managing tunnels to sandbox services. HTTP clients can call
POST /v1/sandbox/:id/tunnel/:portwith an optionalnamebody field for a predictable named URL, andDELETE /v1/sandbox/:id/tunnel/:portto remove the tunnel.
Minor Changes
Prevent stale preview URLs from waking or reaching sandbox runtimes. Invalid, revoked, or destroyed preview URLs return
404 INVALID_TOKEN; authorized URLs that are not activated for the current runtime return410 STALE_PREVIEW_URLuntil the port is exposed again. Existing preview URLs that previously survived container restart now return410 STALE_PREVIEW_URLafter a restart until the port is exposed again in the new runtime.getExposedPorts()andisPortExposed()now report only ports that are currently preview-forwardable in the active runtime.unexposePort()is now idempotent: revoking a port that is not currently exposed succeeds without contacting the container. Preview URL state no longer uses the container-local exposed-port registry or proxy routes.
Patch Changes
Allow backup and restore presigned URLs to target non-default R2 endpoints. Set
BACKUP_BUCKET_ENDPOINT, for examplehttps://<account_id>.eu.r2.cloudflarestorage.com, when your backup bucket uses an R2 jurisdiction.Add bridge endpoints for managing tunnels to sandbox services. HTTP clients can call
POST /v1/sandbox/:id/tunnel/:portwith an optionalnamebody field for a predictable named URL, andDELETE /v1/sandbox/:id/tunnel/:portto remove the tunnel.Classify Office Open XML files such as
.xlsxand.docxas binary when reading files so they are returned with base64 encoding instead of text decoding.Add named-tunnel support to
sandbox.tunnels.get(port, { name }). Named tunnels bind a user-controlled hostname (<name>.<your-zone>) backed by a Cloudflare Tunnel and a proxied CNAME on your zone, so the URL is stable across container restarts and across sandboxes that share the same name. Callingsandbox.destroy()tears down the Cloudflare tunnel and DNS record alongside the container.const tunnel = await sandbox.tunnels.get(8080, { name: 'app' }); console.log(tunnel.url); // → https://app.example.com
- 0.10.x
0.10.3
27 May 2026Bundle
cloudflaredinto the musl/Alpine images.Add sessionless execution mode with a configurable default-session policy.
Set
enableDefaultSession: falseinSandboxOptionsto run implicit top-level operations without a persistent shell — each command gets a fresh process with no shared state. The option is scoped to the sandbox object returned bygetSandbox(...); explicit per-call session IDs continue to target that session.
Patch Changes
Bundle
cloudflaredinto the musl/Alpine images.Add sessionless execution mode with a configurable default-session policy.
Set
enableDefaultSession: falseinSandboxOptionsto run implicit top-level operations without a persistent shell — each command gets a fresh process with no shared state. The option is scoped to the sandbox object returned bygetSandbox(...); explicit per-call session IDs continue to target that session.
0.10.2
21 May 2026Add
sandbox.tunnelsnamespace with quick-tunnel support. Callsandbox.tunnels.get(port)to obtain ahttps://<words>.trycloudflare.comURL that proxies tolocalhost:<port>inside the sandbox. The call is idempotent: repeated calls for the same port return the same record from per-sandbox Durable Object storage. No Cloudflare account or DNS setup required.const tunnel = await sandbox.tunnels.get(8080); console.log(tunnel.url); // → https://random-words-here.trycloudflare.com const same = await sandbox.tunnels.get(8080); console.log(same.url === tunnel.url); // true await sandbox.tunnels.list(); await sandbox.tunnels.destroy(8080); // or destroy(tunnel)
Add credential-less R2 bucket mounting via egress interception
Fix inconsistencies in the sandbox.desktop interface between RPC and HTTP transports
0.10.1
11 May 2026readFilenow acceptsencoding: 'none'on therpctransport, returning a result whosecontentis aReadableStream<Uint8Array>of raw binary data with no base64 encoding or buffering. Mirrors the existingwriteFilesupport forReadableStreaminput.// Stream a binary file without buffering or base64 overhead (rpc transport only) const { content, size, mimeType } = await sandbox.readFile( '/workspace/image.png', { encoding: 'none' } );
0.10.0
7 May 2026Update the default sandbox image runtime from Node.js 20 to Node.js 24 so published images use the current Node.js LTS release. If your workload needs a different Node.js version, build a custom image with the
NODE_VERSIONDocker build argument.Fixed
createBackupandrestoreBackupwithlocalBucket: truefailing on therpctransport for archives larger than ~24 MiB.Add
NODE_VERSIONbuild arg to the Dockerfile, allowing operators to customize the Node.js version used in sandbox container images.
- 0.9.x
0.9.4
6 May 2026Ensure the RPC transport successfully connects once the container has started. This should
reduce the likelihood of hitting anRPCTransportError: WebSocket upgrade failed: 503 Service Unavailableerror when interacting with a sandbox before the container is ready.
0.9.3
5 May 2026Speed up backup and restore for larger archives with faster default compression, multipart R2 uploads, and parallel range downloads that write directly into the restored archive.
Introduce new
rpctransport to consolidatehttpandwebsockettransports.The intention is to replace
httpandwebsockettransports with a single implementation.To enable the transport set
SANDBOX_TRANSPORTtorpcin your wrangler config.A
ReadableStreaminstance can now be passed tosandbox.writeFile()when using therpctransport to avoid the 32mb file limit.{ fetch(req, env) { const sandbox = getSandbox(env.Sandbox, "my-sandbox"); // A ReadableStream can be passed as the content to writeFile(). sandbox.writeFile("/workspace/archive.tar.gz", req.body); return new Response("OK"); } }Surface s3fs mount failures from
mountBucket(). Mount errors (bad credentials, wrong bucket name, network failures) now throwS3FSMountErrorwith the underlyings3fslog output, instead of silently returning success and leaving no filesystem attached.import { S3FSMountError } from '@cloudflare/sandbox'; try { await sandbox.mountBucket('my-bucket', '/mnt/data', { endpoint, credentials }); } catch (err) { if (err instanceof S3FSMountError) { // err.message includes the s3fs log tail, e.g. "403 AccessDenied" } }
0.9.2
29 Apr 2026Fix
createBackup()excludes that use gitignore-style**globstars.Normalize globstar excludes to the mksquashfs-compatible patterns used by the backup pipeline so local and production backups handle them consistently.
0.9.1
27 Apr 2026Coalesce concurrent
Sandbox.destroy()calls onto a single teardown. If a
previousdestroy()is still in flight, subsequent calls await the same
underlying work instead of starting a second teardown, and emit a canonicalsandbox.destroy.coalescedevent per coalesced call for observability.
Once the in-flight teardown settles, laterdestroy()calls run a fresh
teardown as before. Fixes observed destroy-recreate thrash where external
health checks can invokedestroy()faster than the sandbox can initialize.Add
sandbox.getContainerPlacementId()to retrieve the Cloudflare placement ID
observed for the underlying container.The placement ID identifies the current container placement and changes when
the container is replaced by the platform. Compare the returned value against
a stored value to detect container replacement and trigger reconciliation.The placement ID is captured during the session-create handshake and cached
in Durable Object storage, so reads are cheap and do not require a healthy
container. A fresh placement ID is captured on each subsequent handshake,
so a replacement is reflected the next time the sandbox is used.Returns
undefinedwhen no session-create handshake has been observed yet on
this sandbox — call any method that triggers session creation (such asexec()) first. Returnsnullwhen a handshake has completed but the
container'sCLOUDFLARE_PLACEMENT_IDenvironment variable is not set, such as
in local development with wrangler.await sandbox.exec('true'); // ensures the handshake has run const containerPlacementId = await sandbox.getContainerPlacementId(); if ( typeof containerPlacementId === 'string' && containerPlacementId !== lastKnownPlacementId ) { // Container was replaced — reconcile state }
0.9.0
24 Apr 2026Handle shell exits with
SessionTerminatedError, and let the same session id recover on the next call.import { SessionTerminatedError } from '@cloudflare/sandbox'; const session = await sandbox.createSession({ id: 'build' }); try { await session.exec('exit 42'); } catch (error) { if (error instanceof SessionTerminatedError) { console.log(error.exitCode); // 42 await session.exec('echo fresh shell'); } }If a session's shell exits, the failing call now returns
SESSION_TERMINATED
(HTTP 410) with the observed exit code instead of a generic internal error.
Retrying with the same session id, or callingcreateSession({ id }), starts a
fresh session without destroying the whole sandbox. Session-local state such as
the working directory, environment variables, shell functions, and background
jobs is lost when the shell exits.
- 0.8.x
0.8.14
24 Apr 2026Avoid 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.
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.
0.8.11
15 Apr 2026Add the sandbox bridge — an HTTP API that translates REST calls into Sandbox Durable Object operations. Deploy the bridge as a standalone Cloudflare Worker to expose session management, command execution, file read/write, PTY, and workspace mount/unmount over HTTP. Includes an optional warm pool Durable Object for pre-provisioning sandboxes to reduce cold-start latency.
Import the bridge factory and warm pool from
@cloudflare/sandbox/bridge.import { bridge } from '@cloudflare/sandbox/bridge'; export { Sandbox } from '@cloudflare/sandbox'; export { WarmPool } from '@cloudflare/sandbox/bridge'; export default bridge({ fetch(request, env, ctx) { // your code here return new Response('OK'); } });
0.8.10
13 Apr 2026Improve backup restores by mounting backup archives from R2 during restore
instead of downloading them into local container storage first.
0.8.9
10 Apr 2026Fix
unmountBucket()silently succeeding when the FUSE filesystem fails to unmount. The method now checks thefusermountexit code and throwsBucketUnmountErroron failure, cleans up the mount directory after a successful unmount, and the container image includes the/etc/mtabsymlink thatfusermountrequires.Increase the default
gitCheckout()clone timeout to 10 minutes so larger repositories and slower Git remotes do not fail after 2 minutes by default.
You can now override the git clone subprocess timeout per call with thecloneTimeoutMsoption when a checkout needs more time.
0.8.8
9 Apr 2026- Breaking
Require
@cloudflare/containers0.3.0 so sandbox apps pick up the latest Containers platform updates.
0.8.7
8 Apr 2026- Breaking
Require
@cloudflare/containers0.2.3 or newer. Setting
interceptHttps = trueon your Sandbox will now automatically trust the Cloudflare-injected CA certificate at container startup, enabling outbound HTTPS traffic interception.
0.8.6
7 Apr 2026Fix startup deadlock when using WebSocket transport.
Sandboxes that call
exec()or other SDK methods insideonStart()could
get stuck in an infinite timeout loop, requiring a restart. This is now
handled automatically.
0.8.5
7 Apr 2026Allow
createBackup()andrestoreBackup()to target directories under/app.
This makes backups work with custom images that keep application files in/appinstead of/workspace.
0.8.4
1 Apr 2026- Security
Upgrade Go toolchain to 1.25 and update dependencies in the desktop container variant, including a security fix for image processing (CVE-2026-33809).
0.8.3
1 Apr 2026Fix slow parallel code context creation. Creating multiple contexts concurrently (e.g. 10 at once) no longer scales linearly with each request — wall time drops from ~5s to ~500ms.
Add
checkChanges()for apps that disconnect and reconnect later but still need to know whether files changed in the meantime.Use the returned
versionin a later call to learn whether a path is unchanged, changed, or needs a full resync. Retained change state lasts for the current container lifetime only.
0.8.2
1 Apr 2026- Breaking
Require
@cloudflare/containers0.2.2 or newer so long-running streamed commands stay alive pastsleepAfterwhile work is still in progress.
0.8.1
30 Mar 2026Process termination now walks the command's process tree so killing a process also terminates child processes started by that command
0.8.0
26 Mar 2026Add outbound HTTP interception for sandboxes. Define
outboundoroutboundByHosthandlers on your Sandbox class to intercept, modify, or block HTTP requests made from within the sandbox - with full access to Workers bindings like KV and R2.ContainerProxyis also exported directly from@cloudflare/sandbox. Bumps@cloudflare/containersdependency to 0.2.0+.
- 0.7.x
0.7.21
26 Mar 2026Bump picomatch
Structured logging for Workers Observability and Containers Logs. All operations emit queryable fields (
event,outcome,durationMs,command,exitCode,sessionId) that can be filtered and aggregated in the dashboard. Presigned R2 URL parameters and embedded git URL credentials are redacted from all log fields. SetSANDBOX_LOG_FORMAT=prettyfor readable local dev output.
0.7.20
24 Mar 2026Fix supervisor-mode sandbox shutdown so inactivity
SIGTERMcleanly exits the/sandboxprocess even when the user CMD has already exited or daemonized work in the background.
Patch Changes
Fix supervisor-mode sandbox shutdown so inactivity
SIGTERMcleanly exits the/sandboxprocess even when the user CMD has already exited or daemonized work in the background.
0.7.19
23 Mar 2026Add automatic detection of S3 credentials when mounting buckets. Now we do not need to explicitly declare credentials when mounting buckets if they are set as environment variables in the Durable Object.
Fix
sleepAfterconfiguration silently reverting to the default after the sandbox restarts. The configured sleep timeout is now retained reliably across the sandbox lifecycle.Reduce waitIntervalMS default to 300ms
0.7.18
16 Mar 2026Add custom environment variable support to OpenCode integration.
Enable withenvinOpencodeOptionsto pass variables like OTEL endpoints or trace context.Fix environment variables not being inherited by PTY sessions opened via
sandbox.terminal. Variables set withsetEnvVars()were not being passed to the terminal environment.Add local R2 bucket mounting for development via bidirectional sync
0.7.17
10 Mar 2026Add
gitignoreandexcludesoptions tocreateBackup().
0.7.16
10 Mar 2026Pass session env vars and working directory to PTY on creation
0.7.15
10 Mar 2026Improve idle timeout handling for long-running streams over WebSocket transport.
Streams now remain open as long as data is flowing, timing out only after 5 minutes of inactivity.
Support per-command and per-session timeouts for exec
Timeouts now propagate correctly through the full stack. Per-command
timeoutonexec()takes priority over session-levelcommandTimeoutMsset viacreateSession(), which takes priority over the container-levelCOMMAND_TIMEOUT_MSenvironment variable.
0.7.14
9 Mar 2026Fix sandboxes staying awake indefinitely after disabling
keepAlive. CallingsetKeepAlive(false)now correctly re-arms thesleepAftertimeout so the sandbox returns to its configured sleep lifecycle.Add
shelloption toPtyOptionsto allow specifying which shell to spawn (e.g.zsh,sh,fish). Defaults tobashwhen not specified.
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.