Packages

@cloudflare/sandbox

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

Your version

123 stable releases, newest first, by release line. Notes are quoted as the maintainers published them.

  1. 1.x · latest line
  2. 1.0.3

    22 Oct 2026
    • Fix Files.readDirectory() dropping a leading U+FEFF from entry names. Names that start with U+FEFF now come back unchanged, so passing them to stat() or other file operations finds the entry.

  3. 1.0.2

    20 Oct 2026
    • Fix 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.

  4. 1.0.1

    13 Oct 2026
    • Pin Zod 4.6.5, the version that Workers tooling such as @cloudflare/vitest-plugin pins, so a project that installs both installs one copy of Zod instead of two.

  5. 1.0.0

    30 Sep 2026

    1.0.0 is a ground-up rewrite. Your Durable Object extends DurableObject and runs its container through the native ctx.container API. The package adds Files, S3Mount and DirectoryBackup for the work the platform doesn't do itself. Application images copy the sandbox-shim helper from docker.io/cloudflare/sandbox:1.0.0.

  6. 0.12.x
  7. 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 bun command and createBackup() 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 -opencode image ships OpenCode 1.19.4 or later, which also runs on Bun 1.4.4.

  8. 0.12.13

    21 Oct 2026
    • Stop 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 -python image. Bun keeps trusting these certificates until it releases a fix, which affects bun, opencode, and multipart uploads in createBackup() for archives of 10 MiB or more. Update the container image to get this fix. See the eMudhra certificate compromise for details.

  9. 0.12.12

    20 Oct 2026
    • 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 its timeout. 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 EIO until mountBucket() was called again.

  10. 0.12.11

    19 Oct 2026
    • Stop backups from dropping whole directories when excludes or gitignore: true match a nested path. For example, excludes: ['.cache/foo/*/node_modules'] no longer removes all of .cache from the archive. A multi-component pattern such as build/output now matches only relative to the backup directory, while a single-component pattern such as node_modules still matches at any depth. Because mksquashfs does not support **, a pattern like **/node_modules/.cache now excludes only node_modules/.cache at 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_found from the bridge's GET /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.

  11. 0.12.10

    23 Sep 2026
    • Allow multipart backup uploads to trust the runtime HTTPS interception certificate, so backups larger than 10 MiB work when interceptHttps is enabled.

    • Reject bucket-level mutations sent through credentialProxy mounts while preserving object writes, bucket probes, and scoped listings.

    • 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.

  12. 0.12.9

    27 Aug 2026
    • Allow mounted R2 buckets to open object keys containing spaces, symbols, percent signs, and non-ASCII characters.

  13. 0.12.8

    24 Aug 2026
    • Enforce source mount prefixes for server-side copies between R2 bindings.

  14. 0.12.7

    14 Aug 2026
    • Ensure stable releases advance npm's latest tag only after all release artifacts pass verification.

  15. 0.12.6

    13 Aug 2026
    • Enforce mounted bucket and prefix boundaries for server-side copy operations when using credentialProxy.

  16. 0.12.5

    7 Aug 2026
    • Instrument the bridge API with Cloudflare custom spans. Each endpoint now emits
      a bridge.<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 with
      observability.traces.enabled in 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.

  17. 0.12.4

    21 Jul 2026
    • 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.

  18. 0.12.3

    1 Jul 2026
    • Restoring 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, and tunnels.list() no longer returns quick tunnel URLs known to be stale after a container restart.

  19. 0.12.2

    25 Jun 2026
    • 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.

  20. 0.12.1

    9 Jun 2026
    • 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.

  21. 0.12.0

    8 Jun 2026
    • Removed

      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.

    • 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.

    • Fix bucket mounts when a Sandbox class defines a catch-all outbound handler by routing SDK-managed mount hosts through the SDK ContainerProxy.

  22. 0.11.x
  23. 0.11.0

    1 Jun 2026
    • 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.

    • Allow backup and restore presigned URLs to target non-default R2 endpoints. Set BACKUP_BUCKET_ENDPOINT, for example https://<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/:port with an optional name body field for a predictable named URL, and DELETE /v1/sandbox/:id/tunnel/:port to remove the tunnel.

  24. 0.10.x
  25. 0.10.3

    27 May 2026
    • Bundle cloudflared into the musl/Alpine images.

    • 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.

  26. 0.10.2

    21 May 2026
    • Add sandbox.tunnels namespace with quick-tunnel support. Call sandbox.tunnels.get(port) to obtain a https://<words>.trycloudflare.com URL that proxies to localhost:<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

  27. 0.10.1

    11 May 2026
    • readFile now accepts encoding: 'none' on the rpc transport, returning a result whose content is a ReadableStream<Uint8Array> of raw binary data with no base64 encoding or buffering. Mirrors the existing writeFile support for ReadableStream input.

      // Stream a binary file without buffering or base64 overhead (rpc transport only)
      const { content, size, mimeType } = await sandbox.readFile(
        '/workspace/image.png',
        { encoding: 'none' }
      );
  28. 0.10.0

    7 May 2026
    • 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.

    • Fixed createBackup and restoreBackup with localBucket: true failing on the rpc transport for archives larger than ~24 MiB.

    • Add NODE_VERSION build arg to the Dockerfile, allowing operators to customize the Node.js version used in sandbox container images.

  29. 0.9.x
  30. 0.9.4

    6 May 2026
    • 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.

  31. 0.9.3

    5 May 2026
    • 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.

    • Introduce new rpc transport to consolidate http and websocket transports.

      The intention is to replace http and websocket transports with a single implementation.

      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.

      {
        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 throw S3FSMountError with the underlying s3fs log 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"
        }
      }
  32. 0.9.2

    29 Apr 2026
    • 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.

  33. 0.9.1

    27 Apr 2026
    • 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.

    • 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.

      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
      }
  34. 0.9.0

    24 Apr 2026
    • Handle 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 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.

  35. 0.8.x
  36. 0.8.14

    24 Apr 2026
    • 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.

  37. 0.8.11

    15 Apr 2026
    • 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.

      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');
        }
      });
  38. 0.8.10

    13 Apr 2026
    • Improve backup restores by mounting backup archives from R2 during restore
      instead of downloading them into local container storage first.

  39. 0.8.9

    10 Apr 2026
    • 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.

    • 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.

  40. 0.8.8

    9 Apr 2026
  41. 0.8.7

    8 Apr 2026
    • Breaking

      Require @cloudflare/containers 0.2.3 or newer.

    • Setting interceptHttps = true on your Sandbox will now automatically trust the Cloudflare-injected CA certificate at container startup, enabling outbound HTTPS traffic interception.

  42. 0.8.6

    7 Apr 2026
    • 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.

  43. 0.8.5

    7 Apr 2026
    • 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.

  44. 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).

  45. 0.8.3

    1 Apr 2026
    • 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.

    • 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.

  46. 0.8.2

    1 Apr 2026
    • Breaking

      Require @cloudflare/containers 0.2.2 or newer so long-running streamed commands stay alive past sleepAfter while work is still in progress.

  47. 0.8.1

    30 Mar 2026
    • Process termination now walks the command's process tree so killing a process also terminates child processes started by that command

  48. 0.8.0

    26 Mar 2026
    • 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+.

  49. 0.7.x
  50. 0.7.21

    26 Mar 2026
    • Bump 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. Set SANDBOX_LOG_FORMAT=pretty for readable local dev output.

  51. 0.7.20

    24 Mar 2026
    • 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.

  52. 0.7.19

    23 Mar 2026
    • 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.

    • Fix sleepAfter configuration 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

  53. 0.7.18

    16 Mar 2026
    • Add custom environment variable support to OpenCode integration.
      Enable with env in OpencodeOptions to pass variables like OTEL endpoints or trace context.

    • 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.

    • Add local R2 bucket mounting for development via bidirectional sync

  54. 0.7.17

    10 Mar 2026
    • Add gitignore and excludes options to createBackup().

  55. 0.7.16

    10 Mar 2026
    • Pass session env vars and working directory to PTY on creation

  56. 0.7.15

    10 Mar 2026
    • 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.

    • 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.

  57. 0.7.14

    9 Mar 2026
    • 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.

    • Add shell option to PtyOptions to allow specifying which shell to spawn (e.g. zsh, sh, fish). Defaults to bash when 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.