Dockerfile 参考

通过扩展基础运行时镜像，使用自己的软件包、工具和配置自定义沙箱 container 镜像。

基础镜像

Sandbox SDK 提供多个镜像变体。除 -musl 外，其余镜像均基于 Ubuntu。请选择适合你使用场景的镜像：

镜像	标签后缀	用例
默认	（无）	适用于 JavaScript/TypeScript 工作负载的精简镜像
Python	`-python`	数据科学、机器学习、Python 代码执行
OpenCode	`-opencode`	使用 OpenCode CLI 的 AI 编码 Agent
musl	`-musl`	精简版 Alpine 镜像，包含 Git、curl 和 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

Default 镜像

默认镜像针对 JavaScript 和 TypeScript 工作负载进行了优化：

Ubuntu 22.04 LTS 基础
Node.js 22 LTS 和 npm
Bun 1.x（JavaScript/TypeScript 运行时）
系统工具：curl、wget、git、jq、zip、unzip、file、procps、ca-certificates

Python 镜像

-python 变体包含默认镜像中的全部内容，另加：

带 pip 和 venv 的 Python 3.11
预装软件包：matplotlib、numpy、pandas、ipython

OpenCode 镜像

-opencode 变体包含默认镜像中的全部内容，另加：

用于 AI 驱动编码 Agent 的 OpenCode CLI ↗

musl 镜像

-musl 变体是精简镜像：

基于 Alpine Linux 3.21
Git、curl 和 bash
不包含 Node.js、Bun 或 Python

它的 sandbox 二进制文件是为 musl 构建的，因此也能在其他基于 Alpine 的镜像中运行。Docker in Docker 会将其复制到 docker:dind 中。

创建自定义镜像

在项目根目录创建 Dockerfile：

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/*

更新 wrangler.jsonc 以引用你的 Dockerfile：

wrangler.jsoncjsonc

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

当你运行 wrangler dev 或 wrangler deploy 时，Wrangler 会自动构建 Docker 镜像并将其推送到 Cloudflare 的 container registry。你无需手动构建或发布镜像。

使用任意基础镜像

你可以使用独立二进制文件为任何 Docker 镜像添加沙箱能力。此方法允许你使用现有镜像，而无需依赖 Cloudflare 基础镜像：

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"]

/sandbox 二进制文件会启动支持 SDK 通信的 HTTP API 服务器。你还可以选择运行自己的启动命令：

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"]

使用 CMD 时，sandbox 二进制文件会将你的命令作为子进程运行，并正确转发信号。

自定义启动脚本

对于更复杂的启动序列，请创建自定义启动脚本：

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"]

基础镜像已设置正确的 ENTRYPOINT，因此你只需提供 CMD。sandbox 二进制文件会启动 HTTP API 服务器，然后将你的 CMD 作为子进程生成，并正确转发信号。

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

Dockerfile 参考

基础镜像

Default 镜像

Python 镜像

OpenCode 镜像

musl 镜像

创建自定义镜像

使用任意基础镜像

自定义启动脚本

相关资源