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. 0.7.x
  2. 0.7.13

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

  3. 0.7.12

    5 Mar 2026
    • Fix crash when destroying a session that has an active streaming command. The stream now terminates cleanly instead of throwing a null pointer error.

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

  4. 0.7.11

    4 Mar 2026
    • Fix heredoc commands (e.g. cat << 'EOF') hanging permanently and making the session unusable for subsequent commands.

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

  5. 0.7.10

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

  6. 0.7.8

    27 Feb 2026
    • Fix local development crash loops after Docker restarts or idle timeouts. The Sandbox now detects stale container state and automatically recovers.

  7. 0.7.7

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

    • Patch proxyToSandbox to pass redirect responses to the caller, instead of following them

    • Patch readFile to strip MIME type parameters, e.g. text/plain;charset=utf-8 -> text/plain

  8. 0.7.6

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

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

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

  9. 0.7.5

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

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

  10. 0.7.4

    13 Feb 2026
    • Fixes the bug where SDK's expected provider string 'cloudflareAIGateway' (camelCase) isn't recognised by opencode, and thus the opencode example fails to work with ai gateway.Also improved the example code with instructions for ai gateway via unified billing

  11. 0.7.3

    13 Feb 2026
    • Update the OpenCode integration to use the latest @opencode-ai/sdk (v2) client API. Install @opencode-ai/sdk@^1.1.40 to use OpenCode features.

    • Fix fetch() losing its this binding when called on the proxy returned by getSandbox(). This caused preview URL WebSocket routing to fail at runtime.

  12. 0.7.2

    11 Feb 2026
    • Add Alpine-based musl image variant published as cloudflare/sandbox:VERSION-musl.

      A lightweight (51 MB) functional sandbox for Alpine and musl-based containers. Supports all core SDK methods (exec, file operations, git, port exposure, bucket mounting). Does not include Python or Node.js runtimes — add them with apk add to enable runCode().

      As a base image:

      FROM docker.io/cloudflare/sandbox:0.7.2-musl

      Or copy the binary into your own Alpine image:

      COPY --from=docker.io/cloudflare/sandbox:0.7.2-musl /container-server/sandbox /sandbox
    • Allow port 8787 in exposePort(). It was incorrectly blocked.

  13. 0.7.1

    9 Feb 2026
    • Add terminal support for browser-based terminal UIs.

      Build interactive terminal experiences by connecting xterm.js to container PTYs via WebSocket. Terminals reconnect automatically with output history preserved, and each session gets its own isolated terminal.

      // Proxy WebSocket to container terminal
      return sandbox.terminal(request, { cols: 80, rows: 24 });
      
      // Multiple isolated terminals in the same sandbox
      const session = await sandbox.getSession('dev');
      return session.terminal(request);

      Also exports @cloudflare/sandbox/xterm with a SandboxAddon for xterm.js — handles WebSocket connection, reconnection with exponential backoff, and terminal resize forwarding.

      import { SandboxAddon } from '@cloudflare/sandbox/xterm';
      
      const addon = new SandboxAddon({
        getWebSocketUrl: ({ sandboxId, origin }) =>
          `${origin}/ws/terminal?id=${sandboxId}`
      });
      terminal.loadAddon(addon);
      addon.connect({ sandboxId: 'my-sandbox' });
  14. 0.7.0

    14 Jan 2026
    • Add support for custom tokens in exposePort() to enable stable preview URLs across deployments.

      You can now pass a custom token when exposing ports to maintain consistent preview URLs between container restarts and deployments. This is useful for sharing URLs with users or maintaining stable references in production environments.

      // With custom token - URL stays the same across restarts
      const { url } = await sandbox.exposePort(8080, {
        hostname: 'example.com',
        token: 'my_token_v1' // 1-16 chars: a-z, 0-9, _
      });
      // url: https://8080-sandbox-id-my-token-v1.example.com
      
      // Without token - generates random 16-char token (existing behavior)
      const { url } = await sandbox.exposePort(8080, {
        hostname: 'example.com'
      });
      // url: https://8080-sandbox-id-abc123random4567.example.com

      Custom tokens must be 1-16 characters containing only lowercase letters, numbers, and underscores.

      Breaking change: Tokens can no longer contain hyphens. Existing preview URLs with hyphenated tokens (including some auto-generated ones) will stop working until the port is re-exposed.

    • Add Cloudflare AI Gateway support to OpenCode integration. Users can now route AI provider requests through Cloudflare AI Gateway for monitoring, caching, and rate limiting by adding a cloudflareAIGateway provider configuration with accountId, gatewayId, and optional apiToken.

    • Handle undefined environment variables as "unset" in setEnvVars

      Environment variable APIs now properly handle undefined values:

      This enables idiomatic JavaScript patterns:

      await sandbox.setEnvVars({
        API_KEY: 'new-key',
        OLD_SECRET: undefined // unsets OLD_SECRET
      });

      Before: sandbox.setEnvVars({ KEY: undefined }) threw a runtime error
      After: sandbox.setEnvVars({ KEY: undefined }) runs unset KEY

      TypeScript types now honestly accept Record<string, string | undefined>.

  15. 0.6.x
  16. 0.6.11

    13 Jan 2026
    • Mount subdirectories of S3 buckets using the prefix option in mountBucket().

  17. 0.6.10

    6 Jan 2026
    • Add shallow clone support via depth option in gitCheckout(). Use depth: 1 to clone only the latest commit, reducing clone time and disk usage for large repositories.

  18. 0.6.9

    5 Jan 2026
    • Fix sleepAfter option passed to getSandbox() being ignored.

      The custom sleepAfter timeout value is now correctly applied when specified in getSandbox() options.

  19. 0.6.7

    18 Dec 2025
    • Replace HTTP polling with SSE streaming for waitForPort.
      This reduces container log noise and eliminates repeated HTTP requests during port readiness checks.

    • Add WebSocket transport to avoid sub-request limits in Workers and Durable Objects. Set SANDBOX_TRANSPORT=websocket environment variable to multiplex all SDK calls over a single persistent connection.

  20. 0.6.6

    12 Dec 2025
    • Add waitForExit() method to Process interface for waiting until a process terminates

    • Fix race condition for PID retrieval

    • Improve automatic retry behavior for container startup errors

      Transient errors like "container starting" now automatically retry with exponential backoff, while permanent errors like "missing image" fail immediately with clear error messages.

  21. 0.6.5

    11 Dec 2025
    • Add per-session mutex locking to prevent concurrent command execution race conditions

    • Add standalone binary support for arbitrary Dockerfiles

      Users can now add sandbox capabilities to any Docker image:

      FROM your-image:tag
      
      COPY --from=cloudflare/sandbox:VERSION /container-server/sandbox /sandbox
      ENTRYPOINT ["/sandbox"]
      
      # Optional: run your own startup command
      CMD ["/your-entrypoint.sh"]

      The /sandbox binary starts the HTTP API server, then executes any CMD as a child process with signal forwarding.

      Includes backwards compatibility for existing custom startup scripts.

  22. 0.6.4

    10 Dec 2025
    • Add OpenCode integration with createOpencode() and proxyToOpencode() helpers

    • Fix options parameter types for gitCheckout

    • Fix session initialization to eliminate noisy error logs during hot reloads

  23. 0.6.3

    5 Dec 2025
    • Add process readiness detection with port and log pattern waiting
      The Process object returned by startProcess() now includes readiness methods:

  24. 0.6.1

    3 Dec 2025
    • Add top-level await support for JavaScript code execution

      JavaScript code can now use await at the top level without wrapping in an async IIFE. Variables declared with const, let, or var persist across executions, enabling multi-step workflows like:

      // Execution 1
      const data = await fetch('https://api.example.com').then((r) => r.json());
      
      // Execution 2
      console.log(data); // Works - data persists
  25. 0.6.0

    28 Nov 2025
    • Add lean and Python image variants to reduce Docker image size

      BREAKING CHANGE for Python users: The default image no longer includes Python.

      Migration: If using CodeInterpreter.runCode() with Python, update your Dockerfile:

      # Before
      FROM cloudflare/sandbox:0.6.0
      
      # After
      FROM cloudflare/sandbox:0.6.0-python

      Without this change, Python execution will fail with PYTHON_NOT_AVAILABLE error.

  26. 0.5.x
  27. 0.5.6

    27 Nov 2025
    • Removed

      Remove output size limit for command execution

      The 10MB output size limit that was intended to prevent OOM attacks has been removed. This limit was too restrictive for legitimate use cases like reading large media files. Developers are now trusted to manage their own resource usage and handle potential OOM situations.

    • Fix code context isolation bug where contexts leaked state after 10 executions. Each code context now gets a dedicated executor process from creation to deletion, ensuring complete isolation between contexts. Removed maximum pool size limits to allow organic scaling.

    • Fix executor mutex race condition and memory leak in code interpreter

  28. 0.5.4

    25 Nov 2025
    • Add getFileMetadata method in FileService to get only metadata

  29. 0.5.3

    25 Nov 2025
    • Add environment variables and working directory support to command exec

  30. 0.5.2

    24 Nov 2025
    • Remove unused logging infrastructure (getLogger, runWithLogger) that was never called

    • Fix memory leaks from listener accumulation, unbounded process storage, and stale DO state

    • Add OpenAI Agents adapters

      Add OpenAI Agents adapters (Shell and Editor) that integrate Cloudflare Sandbox with the OpenAI Agents SDK. These adapters enable AI agents to execute shell commands and perform file operations (create, update, delete) inside sandboxed environments. Both adapters automatically collect and timestamp results from operations, making it easy to track command execution and file modifications during agent sessions. The adapters are exported from @cloudflare/sandbox/openai and implement the OpenAI Agents Shell and Editor interfaces.

  31. 0.5.1

    18 Nov 2025
    • Add S3-compatible bucket mounting

      Enable mounting S3-compatible buckets (R2, S3, GCS, MinIO, etc.) as local filesystem paths using s3fs-fuse. Supports automatic credential detection from environment variables and intelligent provider detection from endpoint URLs.

    • Improve container startup resiliency

      SDK now retries both 503 (provisioning) and 500 (startup failure) errors automatically. Container timeouts increased to 30s instance + 90s ports (was 8s + 20s).

  32. 0.4.x
  33. 0.4.18

    10 Nov 2025
    • Fix encoding parameter handling in file operations to enable MIME auto-detection. Previously, SDK and container handlers added default 'utf8' encoding, preventing MIME-based detection of binary files. Now encoding parameter is passed through as-is, allowing automatic detection when not explicitly specified.

  34. 0.4.17

    8 Nov 2025
    • Fix container startup failures when WORKDIR is changed in derived Dockerfiles

  35. 0.4.16

    6 Nov 2025
    • Redact credentials from Git URLs in logs

    • Expose deleteSession API with proper safeguards

  36. 0.4.15

    4 Nov 2025
    • Fix foreground commands blocking on background processes

  37. 0.4.14

    30 Oct 2025
    • Add cache mounts to Dockerfile for faster builds

      Adds cache mounts for npm, apt, and pip package managers in the Dockerfile. This speeds up Docker image builds when dependencies change, particularly beneficial for users building from source.

    • Fix type generation

      We inline types from @repo/shared so that it includes the types we reexport. Fixes #165

    • Move .connect to .wsConnect within DO stub

  38. 0.4.12

    29 Oct 2025
    • Add keepAlive flag to prevent containers from shutting down

  39. 0.4.11

    28 Oct 2025
    • Use latest containers package version

  40. 0.4.10

    27 Oct 2025
    • Fix WebSocket upgrade requests through exposed ports

  41. 0.4.9

    24 Oct 2025
    • Add exists() method to check if a file or directory exists

      This adds a new exists() method to the SDK that checks whether a file or directory exists at a given path. The method returns a boolean indicating existence, similar to Python's os.path.exists() and JavaScript's fs.existsSync().

      The implementation is end-to-end:

  42. 0.4.8

    24 Oct 2025
    • Fix token extraction regex causing Invalid token errors

  43. 0.4.7

    23 Oct 2025
    • Fix commands hanging when reading stdin by redirecting stdin to /dev/null

    • Remove unnecessary existing session check

  44. 0.4.6

    22 Oct 2025
    • Add version sync detection between npm package and Docker image

  45. 0.4.5

    22 Oct 2025
    • Configurable sleepAfter

  46. 0.4.4

    21 Oct 2025
  47. 0.4.3

    18 Oct 2025
    • Debloat base docker image (2.63GB → 1.03GB)

  48. 0.4.2

    18 Oct 2025
    • Fix build by inlining repo/shared

  49. 0.4.1

    17 Oct 2025
    • Trigger a release

  50. 0.3.x
  51. 0.3.7

    15 Oct 2025
    • Bake wrangler, vite & opencode in base image

  52. 0.3.6

    14 Oct 2025
    • Set bun idletimeout

  53. 0.3.5

    9 Oct 2025
    • Add binary file support with automatic MIME detection and streaming

  54. 0.3.4

    7 Oct 2025
    • Fix session reuse to reuse existing healthy session

  55. 0.3.3

    3 Oct 2025
    • Bump containers package version

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.