Skip to content
Cloudflare Docs

Dockerfile reference

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

Base image

The Sandbox SDK uses a Ubuntu-based Linux container with Python, Node.js (via Bun), and common development tools pre-installed:

FROM docker.io/cloudflare/sandbox:0.3.3

What's included:

  • Ubuntu 22.04 LTS base
  • Python 3.11 with pip and venv
  • Node.js 20 LTS with npm
  • Bun 1.x (JavaScript/TypeScript runtime)
  • Pre-installed Python packages: matplotlib, numpy, pandas, ipython
  • System utilities: curl, wget, git, jq, zip, unzip, file, procps, ca-certificates

Creating a custom image

Create a Dockerfile in your project root:

Dockerfile
FROM docker.io/cloudflare/sandbox:0.3.3


# 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.jsonc
{
  "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.

Custom startup scripts

Run services automatically when the container starts by creating a custom startup script:

Dockerfile
FROM docker.io/cloudflare/sandbox:0.3.3


COPY my-app.js /workspace/my-app.js
COPY startup.sh /workspace/startup.sh
RUN chmod +x /workspace/startup.sh
CMD ["/workspace/startup.sh"]
startup.sh
#!/bin/bash


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


# Must end with this command
exec bun /container-server/dist/index.js

Your startup script must end with exec bun /container-server/dist/index.js to start the SDK's control plane.

Multiple services

startup.sh
#!/bin/bash


redis-server --daemonize yes
until redis-cli ping; do sleep 1; done


node /workspace/api-server.js &


exec bun /container-server/dist/index.js