git-commit

### Patch Changes - [#895](https://github.com/cloudflare/sandbox-sdk/pull/895) [`db0e68e`](https://github.com/cloudflare/sandbox-sdk/commit/db0e68ef4e9009558cf0e90ae994790c0af03f7c) Thanks [@scuffi](https://github.com/scuffi)! - Allow multipart backup uploads to trust the runtime HTTPS interception certificate, so backups larger than 10 MiB work when `interceptHttps` is enabled. - [#919](https://github.com/cloudflare/sandbox-sdk/pull/919) [`08ab8c9`](https://github.com/cloudflare/sandbox-sdk/commit/08ab8c9430a782683f0937aa13b2d07841f9a459) Thanks [@scuffi](https://github.com/scuffi)! - Reject bucket-level mutations sent through `credentialProxy` mounts while preserving object writes, bucket probes, and scoped listings. - [#922](https://github.com/cloudflare/sandbox-sdk/pull/922) [`f61e8bc`](https://github.com/cloudflare/sandbox-sdk/commit/f61e8bc3a3e25e78b709d28e7f1838d23aa621c1) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Fix `File exists` errors when git or other tools recreate files in a directory restored with `restoreBackup()`, such as running `git reset --hard` while a dev server watches the project.

### Patch Changes - [#877](https://github.com/cloudflare/sandbox-sdk/pull/877) [`664d8e3`](https://github.com/cloudflare/sandbox-sdk/commit/664d8e36d22f2b8f286a9cac90551113afdb316c) Thanks [@scuffi](https://github.com/scuffi)! - Allow mounted R2 buckets to open object keys containing spaces, symbols, percent signs, and non-ASCII characters.

### Patch Changes - [#879](https://github.com/cloudflare/sandbox-sdk/pull/879) [`8534aef`](https://github.com/cloudflare/sandbox-sdk/commit/8534aef9baaeb2adebb974802ba9c325809e6ae6) Thanks [@scuffi](https://github.com/scuffi)! - Enforce source mount prefixes for server-side copies between R2 bindings.

### Patch Changes - [`23a08e4`](https://github.com/cloudflare/sandbox-sdk/commit/23a08e457c96ef3046737214a5cd884a3f9d0c24) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Ensure stable releases advance npm's `latest` tag only after all release artifacts pass verification.

### Patch Changes - [#866](https://github.com/cloudflare/sandbox-sdk/pull/866) [`ae6a900`](https://github.com/cloudflare/sandbox-sdk/commit/ae6a9006f696e86782bae07e0c6ae2234974f82e) Thanks [@scuffi](https://github.com/scuffi)! - Enforce mounted bucket and prefix boundaries for server-side copy operations when using `credentialProxy`.

- [#786](https://github.com/cloudflare/sandbox-sdk/pull/786) [`750ca4d`](https://github.com/cloudflare/sandbox-sdk/commit/750ca4de89d977c1e8127c5ea7c3e03965307aef) Thanks [@aron-cf](https://github.com/aron-cf)! - Instrument the bridge API with Cloudflare custom spans. Each endpoint now emits a `bridge.` 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 with `observability.traces.enabled` in your Worker configuration. - [#799](https://github.com/cloudflare/sandbox-sdk/pull/799) [`0783596`](https://github.com/cloudflare/sandbox-sdk/commit/0783596b334be98a2ab415f1f54ec342e313c10c) Thanks [@aron-cf](https://github.com/aron-cf)! - Make `destroy()` succeed when the sandbox container was never admitted, so cleanup no longer fails with a no-instance platform error. - [#799](https://github.com/cloudflare/sandbox-sdk/pull/799) [`0783596`](https://github.com/cloudflare/sandbox-sdk/commit/0783596b334be98a2ab415f1f54ec342e313c10c) Thanks [@aron-cf](https://github.com/aron-cf)! - Reduce intermittent startup failures during concurrent sandbox creation where operations could fail with a disposed RPC session error. - [#799](https://github.com/cloudflare/sandbox-sdk/pull/799) [`0783596`](https://github.com/cloudflare/sandbox-sdk/commit/0783596b334be98a2ab415f1f54ec342e313c10c) Thanks [@aron-cf](https://github.com/aron-cf)! - Surface container capacity and admission failures as retryable `ContainerUnavailableError` with a structured `reason`, including no-instance and max-instances cases. Callers can branch on `error.reason` instead of parsing platform messages. - [#786](https://github.com/cloudflare/sandbox-sdk/pull/786) [`750ca4d`](https://github.com/cloudflare/sandbox-sdk/commit/750ca4de89d977c1e8127c5ea7c3e03965307aef) Thanks [@aron-cf](https://github.com/aron-cf)! - 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 with `WARM_POOL_SCALE_BATCH_SIZE` (default 5, clamped to 20). - [#786](https://github.com/cloudflare/sandbox-sdk/pull/786) [`750ca4d`](https://github.com/cloudflare/sandbox-sdk/commit/750ca4de89d977c1e8127c5ea7c3e03965307aef) Thanks [@aron-cf](https://github.com/aron-cf)! - 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. - [#786](https://github.com/cloudflare/sandbox-sdk/pull/786) [`750ca4d`](https://github.com/cloudflare/sandbox-sdk/commit/750ca4de89d977c1e8127c5ea7c3e03965307aef) Thanks [@aron-cf](https://github.com/aron-cf)! - Let the warm pool know its instance ceiling up front via the `WARM_POOL_MAX_INSTANCES` bridge variable. Set it to match your container's `max_instances` so the pool makes correct capacity decisions without first crashing into the limit. `0` (the default) preserves the existing auto-learn behaviour.

### Patch Changes - [#798](https://github.com/cloudflare/sandbox-sdk/pull/798) [`33ac27b`](https://github.com/cloudflare/sandbox-sdk/commit/33ac27bbe6698f706bc2aee0435280c869d1465f) Thanks [@aron-cf](https://github.com/aron-cf)! - Add `labels` to `SandboxOptions` so `getSandbox()` can attach Cloudflare Container labels for analytics and observability. Labels are applied on container start; updates while running apply on the next start.

### Patch Changes - [#781](https://github.com/cloudflare/sandbox-sdk/pull/781) [`56b4f78`](https://github.com/cloudflare/sandbox-sdk/commit/56b4f78e630cbbae9d3a59d7fd8bfc8477ba973d) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Restoring a backup now survives a durable object restart. - [#780](https://github.com/cloudflare/sandbox-sdk/pull/780) [`2fec714`](https://github.com/cloudflare/sandbox-sdk/commit/2fec714dc3514177de084df5aefa2ec545c0eb00) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - 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. - [#782](https://github.com/cloudflare/sandbox-sdk/pull/782) [`17d1962`](https://github.com/cloudflare/sandbox-sdk/commit/17d1962db455a176aa78f98b162d1e19b78986bd) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - 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, and `tunnels.list()` no longer returns quick tunnel URLs known to be stale after a container restart.

### Patch Changes - [#778](https://github.com/cloudflare/sandbox-sdk/pull/778) [`b48fa30`](https://github.com/cloudflare/sandbox-sdk/commit/b48fa304e01dc5dd12fe8e5a4d0969d094c9116c) Thanks [@aron-cf](https://github.com/aron-cf)! - Disable the default session for bridge command and file requests. Calls without `Session-Id` now run without reusing shell state; pass `Session-Id` from the session API to preserve working directory or environment across calls.

### Patch Changes - [#748](https://github.com/cloudflare/sandbox-sdk/pull/748) [`ab6206a`](https://github.com/cloudflare/sandbox-sdk/commit/ab6206a9f86de2a367b5e04bee0922592f294e21) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Recover 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.

### Minor Changes - [#739](https://github.com/cloudflare/sandbox-sdk/pull/739) [`9b4b1da`](https://github.com/cloudflare/sandbox-sdk/commit/9b4b1dacad4307b444000f88572b4581927c9781) Thanks [@scuffi](https://github.com/scuffi)! - Remove the desktop client API and desktop Docker image variant. The `sandbox.desktop` APIs, `DesktopClient` exports, desktop-related types/errors, and `-desktop` container image are no longer available. ### Patch Changes - [#727](https://github.com/cloudflare/sandbox-sdk/pull/727) [`2acbd24`](https://github.com/cloudflare/sandbox-sdk/commit/2acbd2436275d09e886c9c38b2afa66fb352d8c0) Thanks [@scuffi](https://github.com/scuffi)! - Add `credentialProxy` option to `mountBucket` to 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. - [#736](https://github.com/cloudflare/sandbox-sdk/pull/736) [`28b5dfa`](https://github.com/cloudflare/sandbox-sdk/commit/28b5dfab4cc422a1fe1ce4d9248ea0b16ac77e80) Thanks [@scuffi](https://github.com/scuffi)! - Fix bucket mounts when a Sandbox class defines a catch-all outbound handler by routing SDK-managed mount hosts through the SDK ContainerProxy. - [#737](https://github.com/cloudflare/sandbox-sdk/pull/737) [`93c74e3`](https://github.com/cloudflare/sandbox-sdk/commit/93c74e3dd3931d9033b81c47ebc2da6177304ae4) Thanks [@scuffi](https://github.com/scuffi)! - Fix phantom `running` processes after a failed `startProcess` call. When the underlying session was unavailable or threw during startup, the process record was left in memory with status `running` and would appear in `listProcesses()` indefinitely. Failed startups are now correctly marked as terminal `error` records.

### Minor Changes - [#708](https://github.com/cloudflare/sandbox-sdk/pull/708) [`287ec04`](https://github.com/cloudflare/sandbox-sdk/commit/287ec04b109645fbc7498efc6c27ddaf088fabed) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - 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 return `410 STALE_PREVIEW_URL` until the port is exposed again. Existing preview URLs that previously survived container restart now return `410 STALE_PREVIEW_URL` after a restart until the port is exposed again in the new runtime. `getExposedPorts()` and `isPortExposed()` 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 - [#733](https://github.com/cloudflare/sandbox-sdk/pull/733) [`d4a739b`](https://github.com/cloudflare/sandbox-sdk/commit/d4a739b9a0d89dc25e0d6b35aaafaa53f02ba40b) Thanks [@scuffi](https://github.com/scuffi)! - Allow backup and restore presigned URLs to target non-default R2 endpoints. Set `BACKUP_BUCKET_ENDPOINT`, for example `https://.eu.r2.cloudflarestorage.com`, when your backup bucket uses an R2 jurisdiction. - [#732](https://github.com/cloudflare/sandbox-sdk/pull/732) [`8b9ec84`](https://github.com/cloudflare/sandbox-sdk/commit/8b9ec84f077078fad6f2f8d5932fd482bd4a1ded) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Add bridge endpoints for managing tunnels to sandbox services. HTTP clients can call `POST /v1/sandbox/:id/tunnel/:port` with an optional `name` body field for a predictable named URL, and `DELETE /v1/sandbox/:id/tunnel/:port` to remove the tunnel. - [#730](https://github.com/cloudflare/sandbox-sdk/pull/730) [`de68927`](https://github.com/cloudflare/sandbox-sdk/commit/de68927b87dc1ba4a213f1a176d2fbcd6f2d102a) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Classify Office Open XML files such as `.xlsx` and `.docx` as binary when reading files so they are returned with base64 encoding instead of text decoding. - [#722](https://github.com/cloudflare/sandbox-sdk/pull/722) [`95bb7b9`](https://github.com/cloudflare/sandbox-sdk/commit/95bb7b97a69c7dcaa5ff0276361840616685ce9d) Thanks [@aron-cf](https://github.com/aron-cf)! - Add named-tunnel support to `sandbox.tunnels.get(port, { name })`. Named tunnels bind a user-controlled hostname (`.`) 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. Calling `sandbox.destroy()` tears down the Cloudflare tunnel and DNS record alongside the container. ```ts const tunnel = await sandbox.tunnels.get(8080, { name: 'app' }); console.log(tunnel.url); // → https://app.example.com ```

### Patch Changes - [#715](https://github.com/cloudflare/sandbox-sdk/pull/715) [`453b577`](https://github.com/cloudflare/sandbox-sdk/commit/453b5771be61e4e7d6a6d1a1088801e7303cd244) Thanks [@aron-cf](https://github.com/aron-cf)! - Upgrade `capnweb` to `0.8.0`. - [#714](https://github.com/cloudflare/sandbox-sdk/pull/714) [`0ec4f42`](https://github.com/cloudflare/sandbox-sdk/commit/0ec4f421d4177ece777ef82a6ec466d6428fab06) Thanks [@aron-cf](https://github.com/aron-cf)! - Bundle `cloudflared` into the musl/Alpine images. - [#706](https://github.com/cloudflare/sandbox-sdk/pull/706) [`ae5f9a1`](https://github.com/cloudflare/sandbox-sdk/commit/ae5f9a10aa45dc59a48c8b9a30c5c14ea16cf75b) Thanks [@scuffi](https://github.com/scuffi)! - Add sessionless execution mode with a configurable default-session policy. Set `enableDefaultSession: false` in `SandboxOptions` to 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 by `getSandbox(...)`; explicit per-call session IDs continue to target that session.

### Patch Changes - [#695](https://github.com/cloudflare/sandbox-sdk/pull/695) [`c6bf7dc`](https://github.com/cloudflare/sandbox-sdk/commit/c6bf7dc48fa3f0199b57ab74753ffa066d09ab92) Thanks [@aron-cf](https://github.com/aron-cf)! - Add `sandbox.tunnels` namespace with quick-tunnel support. Call `sandbox.tunnels.get(port)` to obtain a `https://.trycloudflare.com` URL that proxies to `localhost:` 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. ```ts 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) ``` - [#691](https://github.com/cloudflare/sandbox-sdk/pull/691) [`3ca24fc`](https://github.com/cloudflare/sandbox-sdk/commit/3ca24fc37983d3e14aa95ec29d41ef6788d1a2fa) Thanks [@scuffi](https://github.com/scuffi)! - Add credential-less R2 bucket mounting via egress interception - [#703](https://github.com/cloudflare/sandbox-sdk/pull/703) [`68c8b71`](https://github.com/cloudflare/sandbox-sdk/commit/68c8b71343274937b76282498dfda87a0f4955c2) Thanks [@aron-cf](https://github.com/aron-cf)! - Fix inconsistencies in the sandbox.desktop interface between RPC and HTTP transports

### Patch Changes - [#683](https://github.com/cloudflare/sandbox-sdk/pull/683) [`718d4e7`](https://github.com/cloudflare/sandbox-sdk/commit/718d4e77def490af3250de1a073cc71dbedc13e7) Thanks [@aron-cf](https://github.com/aron-cf)! - `readFile` now accepts `encoding: 'none'` on the `rpc` transport, returning a result whose `content` is a `ReadableStream` of raw binary data with no base64 encoding or buffering. Mirrors the existing `writeFile` support for `ReadableStream` input. ```ts // Stream a binary file without buffering or base64 overhead (rpc transport only) const { content, size, mimeType } = await sandbox.readFile( '/workspace/image.png', { encoding: 'none' } ); ```

### Minor Changes - [#659](https://github.com/cloudflare/sandbox-sdk/pull/659) [`7c09e87`](https://github.com/cloudflare/sandbox-sdk/commit/7c09e874e24dbf6147d3cc6da16b5e327b66cdd8) Thanks [@mvanhorn](https://github.com/mvanhorn)! - Update 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_VERSION` Docker build argument. ### Patch Changes - [#679](https://github.com/cloudflare/sandbox-sdk/pull/679) [`21a5a2e`](https://github.com/cloudflare/sandbox-sdk/commit/21a5a2e2032b684ba0f112601195db6ddaf7091b) Thanks [@aron-cf](https://github.com/aron-cf)! - Fixed `createBackup` and `restoreBackup` with `localBucket: true` failing on the `rpc` transport for archives larger than ~24 MiB. - [#659](https://github.com/cloudflare/sandbox-sdk/pull/659) [`7c09e87`](https://github.com/cloudflare/sandbox-sdk/commit/7c09e874e24dbf6147d3cc6da16b5e327b66cdd8) Thanks [@mvanhorn](https://github.com/mvanhorn)! - Add `NODE_VERSION` build arg to the Dockerfile, allowing operators to customize the Node.js version used in sandbox container images.

### Patch Changes - [#669](https://github.com/cloudflare/sandbox-sdk/pull/669) [`10d3239`](https://github.com/cloudflare/sandbox-sdk/commit/10d323951cd5bba445f4cf9edd060f6a09b99e39) Thanks [@aron-cf](https://github.com/aron-cf)! - Ensure the RPC transport successfully connects once the container has started. This should reduce the likelihood of hitting an `RPCTransportError: WebSocket upgrade failed: 503 Service Unavailable` error when interacting with a sandbox before the container is ready.

### Patch Changes - [#666](https://github.com/cloudflare/sandbox-sdk/pull/666) [`e8f57c8`](https://github.com/cloudflare/sandbox-sdk/commit/e8f57c86896a6740aa434c794986b6e2b53c96dd) Thanks [@scuffi](https://github.com/scuffi)! - Speed 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. - [#647](https://github.com/cloudflare/sandbox-sdk/pull/647) [`68c4f9b`](https://github.com/cloudflare/sandbox-sdk/commit/68c4f9b9262179af4bae3e74125bbce36ab51dca) Thanks [@aron-cf](https://github.com/aron-cf)! - Introduce new `rpc` transport to consolidate `http` and `websocket` transports. The intention is to replace `http` and `websocket` transports with a single implementation. - No sub-request limitations (currently affects the `http` transport). - No limit on write file size (currently affects both `http` and `websocket` transports). To enable the transport set `SANDBOX_TRANSPORT` to `rpc` in your wrangler config. A `ReadableStream` instance can now be passed to `sandbox.writeFile()` when using the `rpc` transport to avoid the 32mb file limit. ```js { 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"); } } ``` - [#653](https://github.com/cloudflare/sandbox-sdk/pull/653) [`e18ba4d`](https://github.com/cloudflare/sandbox-sdk/commit/e18ba4d51e6bebb4c87e03756c4588c7fe3d8272) Thanks [@ask-bonk](https://github.com/apps/ask-bonk)! - Surface s3fs mount failures from `mountBucket()`. Mount errors (bad credentials, wrong bucket name, network failures) now throw `S3FSMountError` with the underlying `s3fs` log output, instead of silently returning success and leaving no filesystem attached. ```ts 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" } } ```

### Patch Changes - [#645](https://github.com/cloudflare/sandbox-sdk/pull/645) [`2d0687b`](https://github.com/cloudflare/sandbox-sdk/commit/2d0687bb1c1b177982b25582a1e4f767be4497af) Thanks [@scuffi](https://github.com/scuffi)! - Fix `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.

### Patch Changes - [`51f1d04`](https://github.com/cloudflare/sandbox-sdk/commit/51f1d04b6faf5b36470a030d01e38480c8810553) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Coalesce concurrent `Sandbox.destroy()` calls onto a single teardown. If a previous `destroy()` is still in flight, subsequent calls await the same underlying work instead of starting a second teardown, and emit a canonical `sandbox.destroy.coalesced` event per coalesced call for observability. Once the in-flight teardown settles, later `destroy()` calls run a fresh teardown as before. Fixes observed destroy-recreate thrash where external health checks can invoke `destroy()` faster than the sandbox can initialize. - [#592](https://github.com/cloudflare/sandbox-sdk/pull/592) [`b2bf021`](https://github.com/cloudflare/sandbox-sdk/commit/b2bf021025bd31fe875626b8751929c3b2ec7478) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - 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 `undefined` when no session-create handshake has been observed yet on this sandbox — call any method that triggers session creation (such as `exec()`) first. Returns `null` when a handshake has completed but the container's `CLOUDFLARE_PLACEMENT_ID` environment variable is not set, such as in local development with wrangler. ```ts 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 } ```

### Minor Changes - [#633](https://github.com/cloudflare/sandbox-sdk/pull/633) [`4e628ae`](https://github.com/cloudflare/sandbox-sdk/commit/4e628ae942a49dda06e1bf68daa669e179f7ffd9) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Handle shell exits with `SessionTerminatedError`, and let the same session id recover on the next call. ```ts 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 calling `createSession({ 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.

### Patch Changes - [#613](https://github.com/cloudflare/sandbox-sdk/pull/613) [`174313f`](https://github.com/cloudflare/sandbox-sdk/commit/174313fa061be7604df5b3cfd4c1770454b727a6) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - 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. - [#624](https://github.com/cloudflare/sandbox-sdk/pull/624) [`bbdfd95`](https://github.com/cloudflare/sandbox-sdk/commit/bbdfd95f70bd73a1c18b49dde139662041143d72) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - 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. - [#629](https://github.com/cloudflare/sandbox-sdk/pull/629) [`34e3a96`](https://github.com/cloudflare/sandbox-sdk/commit/34e3a968abe2eb5efe0d9461c0a90930ca0e0338) Thanks [@aron-cf](https://github.com/aron-cf)! - 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. - [#576](https://github.com/cloudflare/sandbox-sdk/pull/576) [`9222fd0`](https://github.com/cloudflare/sandbox-sdk/commit/9222fd0c408c9dd51b3f262e203b7c5754d650fb) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - 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. - [#614](https://github.com/cloudflare/sandbox-sdk/pull/614) [`74a58e9`](https://github.com/cloudflare/sandbox-sdk/commit/74a58e9692534d1c6faee1757a9eba1380335d07) Thanks [@aron-cf](https://github.com/aron-cf)! - 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. ```ts const sandbox = getSandbox(env.Sandbox, 'my-sandbox', { transport: 'websocket' }); ``` - [#567](https://github.com/cloudflare/sandbox-sdk/pull/567) [`1c7337a`](https://github.com/cloudflare/sandbox-sdk/commit/1c7337a3dfa414b9dd07e2188fec79cb3136977f) Thanks [@scuffi](https://github.com/scuffi)! - Adds support for local backup and restore through the `BACKUP_BUCKET` R2 binding in local development when `localBucket: true` is set.

### Patch Changes - [#585](https://github.com/cloudflare/sandbox-sdk/pull/585) [`ab84333`](https://github.com/cloudflare/sandbox-sdk/commit/ab843334764e0fe0fe268e406f2332d3381bd94e) Thanks [@aron-cf](https://github.com/aron-cf)! - Add 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`. ```ts 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'); } }); ```

### Patch Changes - [#577](https://github.com/cloudflare/sandbox-sdk/pull/577) [`a56898c`](https://github.com/cloudflare/sandbox-sdk/commit/a56898cc83944a5d43ce3ab75cdba8025d51e2fc) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Improve backup restores by mounting backup archives from R2 during restore instead of downloading them into local container storage first.

### Patch Changes - [#570](https://github.com/cloudflare/sandbox-sdk/pull/570) [`8363119`](https://github.com/cloudflare/sandbox-sdk/commit/8363119c5cf70a48a81a7a515fb14a9c0ae890be) Thanks [@aron-cf](https://github.com/aron-cf)! - Fix `unmountBucket()` silently succeeding when the FUSE filesystem fails to unmount. The method now checks the `fusermount` exit code and throws `BucketUnmountError` on failure, cleans up the mount directory after a successful unmount, and the container image includes the `/etc/mtab` symlink that `fusermount` requires. - [#573](https://github.com/cloudflare/sandbox-sdk/pull/573) [`cc14fc7`](https://github.com/cloudflare/sandbox-sdk/commit/cc14fc7e931f7b92cee05010eeb5aa74cc44209b) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - 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 the `cloneTimeoutMs` option when a checkout needs more time.

### Patch Changes - [#571](https://github.com/cloudflare/sandbox-sdk/pull/571) [`c5db840`](https://github.com/cloudflare/sandbox-sdk/commit/c5db84092ad8d3ea1c0e98b54e1b58d7a953b32b) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Require `@cloudflare/containers` 0.3.0 so sandbox apps pick up the latest Containers platform updates.

### Patch Changes - [#565](https://github.com/cloudflare/sandbox-sdk/pull/565) [`ffcbd3a`](https://github.com/cloudflare/sandbox-sdk/commit/ffcbd3ab9584c7e717f6d4d19538bb57cbd88d69) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Require `@cloudflare/containers` 0.2.3 or newer. - [#550](https://github.com/cloudflare/sandbox-sdk/pull/550) [`1db32ea`](https://github.com/cloudflare/sandbox-sdk/commit/1db32ea02f1374b4c79d9bf05f50424b4166402b) Thanks [@scuffi](https://github.com/scuffi)! - Setting `interceptHttps = true` on your Sandbox will now automatically trust the Cloudflare-injected CA certificate at container startup, enabling outbound HTTPS traffic interception.

### Patch Changes - [#557](https://github.com/cloudflare/sandbox-sdk/pull/557) [`f17045b`](https://github.com/cloudflare/sandbox-sdk/commit/f17045ba9202d2a1d0e59161b279fd75a31d458f) Thanks [@AshishKumar4](https://github.com/AshishKumar4)! - Fix startup deadlock when using WebSocket transport. Sandboxes that call `exec()` or other SDK methods inside `onStart()` could get stuck in an infinite timeout loop, requiring a restart. This is now handled automatically.

### Patch Changes - [#559](https://github.com/cloudflare/sandbox-sdk/pull/559) [`b42a57f`](https://github.com/cloudflare/sandbox-sdk/commit/b42a57f712a711d8892a07022ff589bbea4bafce) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Allow `createBackup()` and `restoreBackup()` to target directories under `/app`. This makes backups work with custom images that keep application files in `/app` instead of `/workspace`.

### Patch Changes - [#542](https://github.com/cloudflare/sandbox-sdk/pull/542) [`eb55c28`](https://github.com/cloudflare/sandbox-sdk/commit/eb55c286ac508a70e53f1f7acfaa4f8c1e84156a) Thanks [@dependabot](https://github.com/apps/dependabot)! - Upgrade Go toolchain to 1.25 and update dependencies in the desktop container variant, including a security fix for image processing (CVE-2026-33809).

### Patch Changes - [#515](https://github.com/cloudflare/sandbox-sdk/pull/515) [`bf54f69`](https://github.com/cloudflare/sandbox-sdk/commit/bf54f696790ed9ef6b83ea4c6d3caef881940f4c) Thanks [@Muhammad-Bin-Ali](https://github.com/Muhammad-Bin-Ali)! - Fix 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. - [#493](https://github.com/cloudflare/sandbox-sdk/pull/493) [`fdd3efa`](https://github.com/cloudflare/sandbox-sdk/commit/fdd3efa45a97198c7b69c8578885ca29af803680) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Add `checkChanges()` for apps that disconnect and reconnect later but still need to know whether files changed in the meantime. Use the returned `version` in 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.

### Patch Changes - [#544](https://github.com/cloudflare/sandbox-sdk/pull/544) [`9a2f553`](https://github.com/cloudflare/sandbox-sdk/commit/9a2f553b06cf15a38e629de49d0d7b1d0bec10b7) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Require `@cloudflare/containers` 0.2.2 or newer so long-running streamed commands stay alive past `sleepAfter` while work is still in progress.

### Patch Changes - [#487](https://github.com/cloudflare/sandbox-sdk/pull/487) [`19076fb`](https://github.com/cloudflare/sandbox-sdk/commit/19076fb6c80d2981c2f2e40dcda0911247e81543) Thanks [@scuffi](https://github.com/scuffi)! - Process termination now walks the command's process tree so killing a process also terminates child processes started by that command

### Minor Changes - [#519](https://github.com/cloudflare/sandbox-sdk/pull/519) [`4103149`](https://github.com/cloudflare/sandbox-sdk/commit/41031498a412f2bff125254d8d5b904a508b3847) Thanks [@scuffi](https://github.com/scuffi)! - Add outbound HTTP interception for sandboxes. Define `outbound` or `outboundByHost` handlers 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. `ContainerProxy` is also exported directly from `@cloudflare/sandbox`. Bumps `@cloudflare/containers` dependency to 0.2.0+.

### Patch Changes - [#523](https://github.com/cloudflare/sandbox-sdk/pull/523) [`e3fd7a6`](https://github.com/cloudflare/sandbox-sdk/commit/e3fd7a69a16bc50c36b80fda44301f326a160b91) Thanks [@dependabot](https://github.com/apps/dependabot)! - Bump picomatch - [#456](https://github.com/cloudflare/sandbox-sdk/pull/456) [`734f16d`](https://github.com/cloudflare/sandbox-sdk/commit/734f16d2b1787f5af6798858842d04d3f8dc1c5e) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - 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. Set `SANDBOX_LOG_FORMAT=pretty` for readable local dev output.

### Patch Changes - [#500](https://github.com/cloudflare/sandbox-sdk/pull/500) [`fcfb350`](https://github.com/cloudflare/sandbox-sdk/commit/fcfb35021860927548cd7209f6fc7bea38c53e04) Thanks [@aron-cf](https://github.com/aron-cf)! - Bump wrangler to 4.76.0 - [#486](https://github.com/cloudflare/sandbox-sdk/pull/486) [`db66675`](https://github.com/cloudflare/sandbox-sdk/commit/db66675d437de051384fc6802c30d0785decfaec) Thanks [@berry1001](https://github.com/berry1001)! - Fix supervisor-mode sandbox shutdown so inactivity `SIGTERM` cleanly exits the `/sandbox` process even when the user CMD has already exited or daemonized work in the background.

### Patch Changes - [#503](https://github.com/cloudflare/sandbox-sdk/pull/503) [`05caafc`](https://github.com/cloudflare/sandbox-sdk/commit/05caafc1a746bc98e293776836bb9ae1fdd2f332) Thanks [@scuffi](https://github.com/scuffi)! - Add 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. - [`1c3b75b`](https://github.com/cloudflare/sandbox-sdk/commit/1c3b75b00b3514fbd54ffca7735da5ca3899c6fc) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Fix `sleepAfter` configuration silently reverting to the default after the sandbox restarts. The configured sleep timeout is now retained reliably across the sandbox lifecycle. - [#507](https://github.com/cloudflare/sandbox-sdk/pull/507) [`5e55a38`](https://github.com/cloudflare/sandbox-sdk/commit/5e55a38280f96a84b145d8c4074eb71b4d3f15ff) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Reduce waitIntervalMS default to 300ms

### Patch Changes - [#363](https://github.com/cloudflare/sandbox-sdk/pull/363) [`60967cd`](https://github.com/cloudflare/sandbox-sdk/commit/60967cd15e82929efbbacee00cdfb80d457b3b10) Thanks [@Destreyf](https://github.com/Destreyf)! - Add custom environment variable support to OpenCode integration. Enable with `env` in `OpencodeOptions` to pass variables like OTEL endpoints or trace context. - [#489](https://github.com/cloudflare/sandbox-sdk/pull/489) [`80da532`](https://github.com/cloudflare/sandbox-sdk/commit/80da5321e9154d58ed24db0bb1aa822ed0b70c84) Thanks [@maschwenk](https://github.com/maschwenk)! - Fix environment variables not being inherited by PTY sessions opened via `sandbox.terminal`. Variables set with `setEnvVars()` were not being passed to the terminal environment. - [#468](https://github.com/cloudflare/sandbox-sdk/pull/468) [`378a85c`](https://github.com/cloudflare/sandbox-sdk/commit/378a85c2815755d22ea398a12cf787d0d3c2f72d) Thanks [@scuffi](https://github.com/scuffi)! - Add local R2 bucket mounting for development via bidirectional sync

### Patch Changes - [#474](https://github.com/cloudflare/sandbox-sdk/pull/474) [`5b0ce89`](https://github.com/cloudflare/sandbox-sdk/commit/5b0ce89eedb63d9920eaf82046a12e3837e1b660) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Add `gitignore` and `excludes` options to `createBackup()`. - `gitignore: true` excludes gitignored files when the directory is inside a git repo. If git is not installed, a warning is logged and the backup proceeds without git-based exclusions. - `excludes: string[]` allows explicit glob patterns to exclude from the backup. - Both default to off/empty — existing behavior is unchanged.

### Patch Changes - [#470](https://github.com/cloudflare/sandbox-sdk/pull/470) [`887b032`](https://github.com/cloudflare/sandbox-sdk/commit/887b0321990a3e23f8060229ecc06210affb3f1c) Thanks [@maschwenk](https://github.com/maschwenk)! - Pass session env vars and working directory to PTY on creation

### Patch Changes - [#400](https://github.com/cloudflare/sandbox-sdk/pull/400) [`92e1fda`](https://github.com/cloudflare/sandbox-sdk/commit/92e1fdabb5313b9c23a755cebb9f8807954ca346) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Improve 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. - [#450](https://github.com/cloudflare/sandbox-sdk/pull/450) [`75dc1f9`](https://github.com/cloudflare/sandbox-sdk/commit/75dc1f9ae127479de782934d307c1acdbd2591d2) Thanks [@scuffi](https://github.com/scuffi)! - Support per-command and per-session timeouts for exec Timeouts now propagate correctly through the full stack. Per-command `timeout` on `exec()` takes priority over session-level `commandTimeoutMs` set via `createSession()`, which takes priority over the container-level `COMMAND_TIMEOUT_MS` environment variable.

### Patch Changes - [#476](https://github.com/cloudflare/sandbox-sdk/pull/476) [`440eb1f`](https://github.com/cloudflare/sandbox-sdk/commit/440eb1fa929b8e57d69c055f256f9b9c40f2d36e) Thanks [@berry1001](https://github.com/berry1001)! - Fix sandboxes staying awake indefinitely after disabling `keepAlive`. Calling `setKeepAlive(false)` now correctly re-arms the `sleepAfter` timeout so the sandbox returns to its configured sleep lifecycle. - [#469](https://github.com/cloudflare/sandbox-sdk/pull/469) [`856f4dd`](https://github.com/cloudflare/sandbox-sdk/commit/856f4dd80c853fe857f4ecb88c3dc52a3e0bf110) Thanks [@maschwenk](https://github.com/maschwenk)! - Add `shell` option to `PtyOptions` to allow specifying which shell to spawn (e.g. `zsh`, `sh`, `fish`). Defaults to `bash` when not specified.

### Patch Changes - [#459](https://github.com/cloudflare/sandbox-sdk/pull/459) [`f3e264a`](https://github.com/cloudflare/sandbox-sdk/commit/f3e264ad6d74d50e7410703c9ac51e7f6f656496) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Fix four root causes of intermittent sandbox failures: a debounce deadlock in log pattern matching that caused startups to time out, incorrect HTTP 500 classification for transient startup errors that prevented retries, a WebSocket chunk race where streaming responses dropped data before the controller was ready, and missing timeout protection on git clone operations that could hang indefinitely on slow or unreachable remotes.

### Patch Changes - [#452](https://github.com/cloudflare/sandbox-sdk/pull/452) [`5cce034`](https://github.com/cloudflare/sandbox-sdk/commit/5cce03430392fd47e4fb4bd011add5279d09db2e) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Fix crash when destroying a session that has an active streaming command. The stream now terminates cleanly instead of throwing a null pointer error. - [#449](https://github.com/cloudflare/sandbox-sdk/pull/449) [`909e8c5`](https://github.com/cloudflare/sandbox-sdk/commit/909e8c55d257b76dac65dd22e76996a9f0622a23) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Fix sandbox creation timing out for large container images even when startup timeouts are configured to allow enough time. The transport retry budget now automatically scales to match configured startup timeouts instead of being hard-coded at 120 seconds.

### Patch Changes - [#446](https://github.com/cloudflare/sandbox-sdk/pull/446) [`bbaba54`](https://github.com/cloudflare/sandbox-sdk/commit/bbaba5403e1bc7e062f36c37bfdd72e6683ff965) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Fix heredoc commands (e.g. `cat << 'EOF'`) hanging permanently and making the session unusable for subsequent commands. - [#447](https://github.com/cloudflare/sandbox-sdk/pull/447) [`4088435`](https://github.com/cloudflare/sandbox-sdk/commit/4088435d9dc2ea8965518836d09b966dfe3ae661) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Fix three reliability issues: OpenCode readiness probe returning healthy before the binary is ready, file watch race condition where stale watchers could linger after cancellation, and SSE stream handler registering output listeners after replaying buffered logs — causing intermittent `waitForLog` timeouts on HTTP transport.

### Patch Changes - [#422](https://github.com/cloudflare/sandbox-sdk/pull/422) [`dc70649`](https://github.com/cloudflare/sandbox-sdk/commit/dc706497a3e3014cbca3ab20f456e7f207798097) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Add desktop environment support for AI computer-use workflows. Start a full Linux desktop (Xvfb + XFCE4 + x11vnc + noVNC) inside the sandbox and control it programmatically via `sandbox.desktop.*` methods. Supports screenshots, mouse clicks, keyboard input, and live browser streaming via noVNC preview URLs. Enable with `sandbox.desktop.start()`. Requires the desktop container image variant.

### Patch Changes - [#427](https://github.com/cloudflare/sandbox-sdk/pull/427) [`04b4ccf`](https://github.com/cloudflare/sandbox-sdk/commit/04b4ccf5d6ff180d9e93ff582abd27b7f13ca36d) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Fix local development crash loops after Docker restarts or idle timeouts. The Sandbox now detects stale container state and automatically recovers.

### Patch Changes - [#402](https://github.com/cloudflare/sandbox-sdk/pull/402) [`eb23055`](https://github.com/cloudflare/sandbox-sdk/commit/eb23055ca6d0cf8069628e60eb25290a2cfe90e4) Thanks [@scuffi](https://github.com/scuffi)! - Improve `readFile()` and `readFileStream()` performance by using native syscall file reads instead of shell-based reads. This increases read transfer speeds and unblocks the max throughput from file streaming. Improving file size handling: calls to `readFile()` now return a `413: File too large error` if the target file exceeds `32 MiB`. Previously such files would trigger a generic error; we're now explicit about the limitation and recommend using `readFileStream` for larger files. - [#421](https://github.com/cloudflare/sandbox-sdk/pull/421) [`1244660`](https://github.com/cloudflare/sandbox-sdk/commit/1244660a2fdffa27361f98a998c402ffc36c1151) Thanks [@scuffi](https://github.com/scuffi)! - Patch `proxyToSandbox` to pass redirect responses to the caller, instead of following them - [#430](https://github.com/cloudflare/sandbox-sdk/pull/430) [`364e366`](https://github.com/cloudflare/sandbox-sdk/commit/364e366e2cf15c9d71bd52fa8b7ac5ec93b82039) Thanks [@scuffi](https://github.com/scuffi)! - Patch `readFile` to strip MIME type parameters, e.g. `text/plain;charset=utf-8` -> `text/plain`

### Patch Changes - [#417](https://github.com/cloudflare/sandbox-sdk/pull/417) [`9cbebd8`](https://github.com/cloudflare/sandbox-sdk/commit/9cbebd83ab00fec916216478371c4a6f08f65c2e) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Stream backup archive uploads to presigned R2 URLs with `curl -T` instead of `--data-binary`. This avoids large in-memory payload allocation and improves reliability for multi-GB backups. - [#419](https://github.com/cloudflare/sandbox-sdk/pull/419) [`35f7d65`](https://github.com/cloudflare/sandbox-sdk/commit/35f7d6569ac8c99a9c78f8a1ebb18e122e74b385) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Fix flaky OpenCode E2E test by checking health endpoint readiness Changed `waitForPort` to verify `/global/health` returns HTTP 200 instead of just checking if the server accepts connections at `/`. This ensures the OpenCode server is fully initialized before `createOpencodeServer` returns, preventing 500 errors when tests immediately call the health endpoint. - [#418](https://github.com/cloudflare/sandbox-sdk/pull/418) [`6994598`](https://github.com/cloudflare/sandbox-sdk/commit/6994598220fd5b2bdff23b774b25a01faf0966c6) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Improve error message when backup upload verification fails due to a local/remote R2 mismatch. When using `wrangler dev`, presigned URLs upload to real R2 while the `BACKUP_BUCKET` binding defaults to local storage. The error now suggests adding `"remote": true` to the R2 binding in `wrangler.jsonc`. - [#404](https://github.com/cloudflare/sandbox-sdk/pull/404) [`c602785`](https://github.com/cloudflare/sandbox-sdk/commit/c602785b72d549abe0f60b106b1375b5eaa82e50) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Improve `writeFile()` performance by using native container file writes instead of shell-based write pipelines. This reduces write latency for both UTF-8 and base64 payloads while preserving existing encoding behavior. - [#412](https://github.com/cloudflare/sandbox-sdk/pull/412) [`5abdb55`](https://github.com/cloudflare/sandbox-sdk/commit/5abdb5576e8f677741d597970d8f4d5afc2b4cef) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Fix file writes without an explicit `encoding` so requests use default write options instead of sending `encoding: undefined`.

### Patch Changes - [#396](https://github.com/cloudflare/sandbox-sdk/pull/396) [`76284f0`](https://github.com/cloudflare/sandbox-sdk/commit/76284f02154056b89ce0861373d51966e3fe0f02) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Add backup and restore API for directory snapshots. `createBackup()` archives a directory as a compressed squashfs image and uploads it to R2. `restoreBackup()` downloads and mounts the archive with copy-on-write semantics via FUSE overlay. Requires R2 presigned URL credentials: set `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `CLOUDFLARE_ACCOUNT_ID`, and `BACKUP_BUCKET_NAME` as environment variables alongside the `BACKUP_BUCKET` R2 binding. Archives transfer directly between the container and R2 at ~24 MB/s upload / ~93 MB/s download. - [#403](https://github.com/cloudflare/sandbox-sdk/pull/403) [`bbfc579`](https://github.com/cloudflare/sandbox-sdk/commit/bbfc579645e53f9e1c6ba54760bfa3d249f6de1c) Thanks [@whoiskatrin](https://github.com/whoiskatrin)! - Add `proxyToOpencodeServer()` to proxy requests directly to a running OpenCode server without web UI redirect behavior. Use this helper for headless API and CLI traffic where raw request forwarding is preferred.