@cloudflare/sandbox
1.0.3 · 22 Oct 2026Apache-2.02.1M / weekRepositoryHomepagenpmAtom feed
123 stable releases, newest first, by release line. Notes are quoted as the maintainers published them.
- 0.7.x
0.7.13
6 Mar 2026Fix 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.
0.7.12
5 Mar 2026Fix 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.
0.7.11
4 Mar 2026Fix 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
waitForLogtimeouts on HTTP transport.
0.7.10
3 Mar 2026Add desktop environment support for AI computer-use workflows.
Start a full Linux desktop (Xvfb + XFCE4 + x11vnc + noVNC) inside the
sandbox and control it programmatically viasandbox.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.
0.7.8
27 Feb 2026Fix local development crash loops after Docker restarts or idle timeouts. The Sandbox now detects stale container state and automatically recovers.
0.7.7
27 Feb 2026Improve
readFile()andreadFileStream()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 a413: File too large errorif the target file exceeds32 MiB. Previously such files would trigger a generic error; we're now explicit about the limitation and recommend usingreadFileStreamfor larger files.Patch
proxyToSandboxto pass redirect responses to the caller, instead of following themPatch
readFileto strip MIME type parameters, e.g.text/plain;charset=utf-8->text/plain
0.7.6
25 Feb 2026Stream backup archive uploads to presigned R2 URLs with
curl -Tinstead 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 theBACKUP_BUCKETbinding defaults to local storage. The error now suggests adding"remote": trueto the R2 binding inwrangler.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.
Patch Changes
Stream backup archive uploads to presigned R2 URLs with
curl -Tinstead 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 theBACKUP_BUCKETbinding defaults to local storage. The error now suggests adding"remote": trueto the R2 binding inwrangler.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.Fix file writes without an explicit
encodingso requests use default write options instead of sendingencoding: undefined.
0.7.5
20 Feb 2026Add 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, andBACKUP_BUCKET_NAMEas environment variables alongside theBACKUP_BUCKETR2 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.
0.7.4
13 Feb 2026Fixes 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
0.7.3
13 Feb 2026Update 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 itsthisbinding when called on the proxy returned bygetSandbox(). This caused preview URL WebSocket routing to fail at runtime.
0.7.2
11 Feb 2026Add 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 withapk addto enablerunCode().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.
0.7.1
9 Feb 2026Add 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/xtermwith aSandboxAddonfor 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' });
0.7.0
14 Jan 2026Add 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.comCustom 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
cloudflareAIGatewayprovider configuration withaccountId,gatewayId, and optionalapiToken.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 })runsunset KEYTypeScript types now honestly accept
Record<string, string | undefined>.
- 0.6.x
0.6.11
13 Jan 2026Mount subdirectories of S3 buckets using the
prefixoption inmountBucket().
0.6.10
6 Jan 2026Add shallow clone support via
depthoption ingitCheckout(). Usedepth: 1to clone only the latest commit, reducing clone time and disk usage for large repositories.
0.6.9
5 Jan 2026Fix sleepAfter option passed to getSandbox() being ignored.
The custom sleepAfter timeout value is now correctly applied when specified in getSandbox() options.
0.6.7
18 Dec 2025Replace 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=websocketenvironment variable to multiplex all SDK calls over a single persistent connection.
0.6.6
12 Dec 2025Add 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.
0.6.5
11 Dec 2025Add 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
/sandboxbinary starts the HTTP API server, then executes any CMD as a child process with signal forwarding.Includes backwards compatibility for existing custom startup scripts.
0.6.4
10 Dec 2025Add OpenCode integration with createOpencode() and proxyToOpencode() helpers
Fix
optionsparameter types forgitCheckoutFix session initialization to eliminate noisy error logs during hot reloads
Patch Changes
Add OpenCode integration with createOpencode() and proxyToOpencode() helpers
Fix
optionsparameter types forgitCheckoutFix session initialization to eliminate noisy error logs during hot reloads
Fix workspace bug
0.6.3
5 Dec 2025Add process readiness detection with port and log pattern waiting
TheProcessobject returned bystartProcess()now includes readiness methods:
0.6.1
3 Dec 2025Add top-level await support for JavaScript code execution
JavaScript code can now use
awaitat the top level without wrapping in an async IIFE. Variables declared withconst,let, orvarpersist 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
0.6.0
28 Nov 2025Add 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_AVAILABLEerror.
- 0.5.x
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
Patch Changes
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
- 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.
Close stream before releasing lock
0.5.4
25 Nov 2025Add getFileMetadata method in FileService to get only metadata
0.5.3
25 Nov 2025Add environment variables and working directory support to command exec
0.5.2
24 Nov 2025Remove 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 (
ShellandEditor) 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/openaiand implement the OpenAI AgentsShellandEditorinterfaces.
0.5.1
18 Nov 2025Add 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).
Patch Changes
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).
- 0.4.x
0.4.18
10 Nov 2025Fix 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.
0.4.17
8 Nov 2025Fix container startup failures when WORKDIR is changed in derived Dockerfiles
0.4.16
6 Nov 2025Redact credentials from Git URLs in logs
Expose deleteSession API with proper safeguards
0.4.15
4 Nov 2025Fix foreground commands blocking on background processes
Patch Changes
Fix foreground commands blocking on background processes
0.4.14
30 Oct 2025Add 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/sharedso that it includes the types we reexport. Fixes #165Move .connect to .wsConnect within DO stub
Patch Changes
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/sharedso that it includes the types we reexport. Fixes #165Move .connect to .wsConnect within DO stub
0.4.12
29 Oct 2025Add keepAlive flag to prevent containers from shutting down
0.4.11
28 Oct 2025Use latest containers package version
0.4.10
27 Oct 2025Fix WebSocket upgrade requests through exposed ports
0.4.9
24 Oct 2025Add 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'sos.path.exists()and JavaScript'sfs.existsSync().The implementation is end-to-end:
0.4.8
24 Oct 2025Fix token extraction regex causing Invalid token errors
0.4.7
23 Oct 2025Fix commands hanging when reading stdin by redirecting stdin to /dev/null
Remove unnecessary existing session check
0.4.6
22 Oct 2025Add version sync detection between npm package and Docker image
0.4.5
22 Oct 2025Configurable sleepAfter
0.4.4
21 Oct 2025fddccfdThanks @whoiskatrin! - add docker image to pkg workflow
0.4.3
18 Oct 2025Debloat base docker image (2.63GB → 1.03GB)
0.4.2
18 Oct 2025Fix build by inlining repo/shared
0.4.1
17 Oct 2025Trigger a release
- 0.3.x
0.3.7
15 Oct 2025Bake wrangler, vite & opencode in base image
0.3.6
14 Oct 2025Set bun idletimeout
0.3.5
9 Oct 2025Add binary file support with automatic MIME detection and streaming
0.3.4
7 Oct 2025Fix session reuse to reuse existing healthy session
0.3.3
3 Oct 2025Bump 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.