Dockerfile reference

Dockerfile reference

Last updated Oct 23, 2026 Note

This page documents Sandbox SDK 0.x for existing applications. For new applications, refer to Sandboxes. To move an existing application to @cloudflare/sandbox 1.0, refer to Migrate from Sandbox SDK 0.x.

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 image variants. All except -musl are based on Ubuntu. 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
musl	`-musl`	Minimal Alpine image with Git, curl, and bash

# Default - lean, no Python
FROM docker.io/cloudflare/sandbox:0.12.14

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

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

# musl - minimal Alpine image, no Node.js, Bun, or Python
FROM docker.io/cloudflare/sandbox:0.12.14-musl

Version synchronization required

Always match the Docker image version to your npm package version. If you are using @cloudflare/sandbox@0.12.14, use docker.io/cloudflare/sandbox:0.12.14 (or variant) as your base image.

Why this matters: The SDK automatically checks version compatibility on startup. Mismatched versions can cause features to break or behave unexpectedly. If versions don't match, you'll see warnings in your logs.

See Version compatibility for troubleshooting version mismatch warnings.

Default image

The default image is optimized for JavaScript and TypeScript workloads:

Ubuntu 22.04 LTS base
Node.js 22 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:

OpenCode CLI ↗︎ for AI-powered coding agents

musl image

The -musl variant is a minimal image:

Alpine Linux 3.21 base
Git, curl, and bash
No Node.js, Bun, or Python

Its sandbox binary is built for musl, so it also runs in other Alpine-based images. Docker in Docker copies it into docker:dind.

Creating a custom image

Create a Dockerfile in your project root:

Dockerfiledockerfile

FROM docker.io/cloudflare/sandbox:0.12.14-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.12.14 /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:22-slim

COPY --from=docker.io/cloudflare/sandbox:0.12.14 /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.12.14-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

Legacy startup scripts

If you have existing startup scripts that end with exec bun /container-server/dist/index.js, they will continue to work for backwards compatibility. However, we recommend migrating to the new approach using CMD for your startup script. Do not override ENTRYPOINT when extending the base image.

Image Management - Building and pushing images to Cloudflare's registry
Wrangler configuration - Using custom images in wrangler.jsonc
Docker documentation ↗︎ - Complete Dockerfile syntax
Container concepts - Understanding the runtime environment

Was this helpful?

YesNo

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/sandbox/sdk/configuration/dockerfile/#page","headline":"Dockerfile reference","description":"Customize the Sandbox SDK 0.x container image with packages, tools, and configurations.","url":"https://developers.cloudflare.com/sandbox/sdk/configuration/dockerfile/","inLanguage":"en","image":"https://developers.cloudflare.com/sandbox/sdk/configuration/dockerfile/og.png?v=b9a687a555db7761","dateModified":"2026-10-23","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Pass configuration, secrets, and runtime settings to Sandbox SDK 0.x containers using environment variables. title: Environment variables image: https://developers.cloudflare.com/sandbox/sdk/configuration/environment-variables/og.png?v=059d82691308ae62

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/sandbox/llms.txt
Use this file to discover all available pages before exploring further.

Dockerfile reference

Dockerfile reference

Base images

Default image

Python image

OpenCode image

musl image

Creating a custom image

Using arbitrary base images

Custom startup scripts

Related resources

On this page