Pular para o conteúdo

Dockerfile reference

Atualizado em Ver como Markdown

Customize the sandbox container image with your own packages, tools, and configurations by extending the base runtime image.

Base images

The Sandbox SDK provides multiple Ubuntu-based image variants. Choose the one that fits your use case:

Image Tag suffix Use case
Default (none) Lean image for JavaScript/TypeScript workloads
Python -python Data science, ML, Python code execution
OpenCode -opencode AI coding agents with OpenCode CLI 
# Default - lean, no Python
FROM docker.io/cloudflare/sandbox:0.7.0

# Python - includes Python 3.11 + data science packages
FROM docker.io/cloudflare/sandbox:0.7.0-python

# OpenCode - includes OpenCode CLI for AI coding
FROM docker.io/cloudflare/sandbox:0.7.0-opencode

Default image

The default image is optimized for JavaScript and TypeScript workloads:

  • Ubuntu 22.04 LTS base
  • Node.js 20 LTS with npm
  • Bun 1.x (JavaScript/TypeScript runtime)
  • System utilities: curl, wget, git, jq, zip, unzip, file, procps, ca-certificates

Python image

The -python variant includes everything in the default image plus:

  • Python 3.11 with pip and venv
  • Pre-installed packages: matplotlib, numpy, pandas, ipython

OpenCode image

The -opencode variant includes everything in the default image plus:

Creating a custom image

Create a Dockerfile in your project root:

Dockerfiledockerfile
FROM docker.io/cloudflare/sandbox:0.7.0-python

# Install additional Python packages
RUN pip install --no-cache-dir \
    scikit-learn==1.3.0 \
    tensorflow==2.13.0 \
    transformers==4.30.0

# Install Node.js packages globally
RUN npm install -g typescript ts-node prettier

# Install system packages
RUN apt-get update && apt-get install -y \
    postgresql-client \
    redis-tools \
    && rm -rf /var/lib/apt/lists/*

Update wrangler.jsonc to reference your Dockerfile:

wrangler.jsoncjsonc
{
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
		},
	],
}

When you run wrangler dev or wrangler deploy, Wrangler automatically builds your Docker image and pushes it to Cloudflare's container registry. You don't need to manually build or publish images.

Using arbitrary base images

You can add sandbox capabilities to any Docker image using the standalone binary. This approach lets you use your existing images without depending on the Cloudflare base images:

Dockerfiledockerfile
FROM your-custom-image:tag

# Copy the sandbox binary from the official image
COPY --from=docker.io/cloudflare/sandbox:0.7.0 /container-server/sandbox /sandbox

ENTRYPOINT ["/sandbox"]

The /sandbox binary starts the HTTP API server that enables SDK communication. You can optionally run your own startup command:

Dockerfiledockerfile
FROM node:20-slim

COPY --from=docker.io/cloudflare/sandbox:0.7.0 /container-server/sandbox /sandbox

# Copy your application
COPY . /app
WORKDIR /app

ENTRYPOINT ["/sandbox"]
CMD ["node", "server.js"]

When using CMD, the sandbox binary runs your command as a child process with proper signal forwarding.

Custom startup scripts

For more complex startup sequences, create a custom startup script:

Dockerfiledockerfile
FROM docker.io/cloudflare/sandbox:0.7.0-python

COPY my-app.js /workspace/my-app.js
COPY startup.sh /workspace/startup.sh
RUN chmod +x /workspace/startup.sh

CMD ["/workspace/startup.sh"]

The base image already sets the correct ENTRYPOINT, so you only need to provide a CMD. The sandbox binary starts the HTTP API server, then spawns your CMD as a child process with proper signal forwarding.

startup.shbash
#!/bin/bash

# Start your services in the background
node /workspace/my-app.js &

# Start additional services
redis-server --daemonize yes
until redis-cli ping; do sleep 1; done

# Keep the script running (the sandbox binary handles the API server)
wait