Skip to content

DOCKER_README.md

Latest commit

 

History

History
94 lines (69 loc) · 3.83 KB

DOCKER_README.md

File metadata and controls

94 lines (69 loc) · 3.83 KB
Raw

Cloudflare Sandbox

Secure, isolated code execution containers for Cloudflare Workers. Run untrusted code safely — execute commands, manage files, run background processes, and expose services from your Workers applications.

Image Variants

All images are published as tags on cloudflare/sandbox:

Tag Base Description
<version> Ubuntu 22.04 Default — Node.js 24, Bun, Git, curl, jq, and common utilities
<version>-python Ubuntu 22.04 Default + Python 3.11 with matplotlib, numpy, pandas, ipython
<version>-opencode Ubuntu 22.04 Default + OpenCode CLI
<version>-musl Alpine 3.21 Minimal Alpine-based image with Git, curl, and bash

Usage

These images are designed to be used with the @cloudflare/sandbox SDK. Reference them in your project's Dockerfile:

FROM cloudflare/sandbox:0.12.9-python

Then configure your wrangler.toml to use the image:

[containers]
image = "./Dockerfile"
max_instances = 1

See the Getting Started guide for a complete walkthrough.

Custom Node.js versions

Published sandbox images include Node.js 24 by default. If your workload requires a different Node.js version, build a custom image with the NODE_VERSION Docker build argument:

docker buildx build \
  --build-arg NODE_VERSION=22 \
  --target default \
  -f packages/sandbox/Dockerfile \
  .

Architecture

Each image runs a lightweight HTTP server (port 3000) that the Sandbox SDK communicates with. The server handles command execution, file operations, process management, and port exposure. Images are built for linux/amd64.

Local development behind a TLS-intercepting proxy

If your machine runs Cloudflare WARP / Zero Trust (or any other proxy that re-signs TLS with a corporate root), the sandbox container must trust that root or outbound HTTPS calls fail with x509: certificate signed by unknown authority. The Dockerfile accepts a wrangler_ca build secret that gets appended to the image's CA bundle and registered with update-ca-certificates:

docker build \
  -f packages/sandbox/Dockerfile \
  --target default \
  --secret id=wrangler_ca,src="$NODE_EXTRA_CA_CERTS" \
  -t my-sandbox-image .

WARP's installer sets NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, and REQUESTS_CA_BUNDLE to a bundle that includes the corporate root, so passing $NODE_EXTRA_CA_CERTS is the easiest way to wire it through. Local builds done via npm run docker:rebuild already pass this secret — you only need this when invoking docker build directly.

When the secret isn't passed (CI, fresh checkout without WARP), the build is a no-op and the resulting image trusts only the standard public CAs.

Known limitation for sandbox.tunnels. Even with the CA bundle trusted, WARP's Zero Trust egress policy can block outbound traffic to api.trycloudflare.com and the cloudflared edge endpoints outright. When that happens, tunnels.create() hangs waiting for the edge handshake and eventually times out. The workaround is to run with WARP disabled or to add an egress exception for those destinations.

Documentation

License

Apache License 2.0