Cloudflare 沙箱 SDK

在 Cloudflare 上构建安全、隔离的代码执行环境。

Sandbox SDK 允许您在隔离的容器中安全地运行不受信任的代码。您可以从 Workers 应用程序中执行命令、管理文件、运行后台进程以及暴露服务。

非常适合用于 AI 代码执行、交互式开发环境、数据分析平台、CI/CD 系统，以及任何需要在边缘进行安全代码执行的应用场景。

快速入门

前提条件

1. 安装 Node.js（版本 16.17.0 或更高）
2. 确保本地已运行 Docker（参见设置指南）
3. 若要部署到生产环境，请注册一个 Cloudflare 账户

1. 创建新项目

使用最小模板创建一个新的 Sandbox SDK 项目：

npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal
cd my-sandbox

2. 在本地测试

启动开发服务器：

npm run dev

注意： 首次运行会构建 Docker 容器（2-3 分钟）。后续运行会快得多。

测试端点：

# 执行 Python 代码
curl http://localhost:8787/run

# 文件操作
curl http://localhost:8787/file

3. 部署到生产环境

部署您的 Worker 和容器：

npx wrangler deploy

等待资源调配： 首次部署后，请等待 2-3 分钟再发起请求。

📖 查看完整的入门指南，获取详细说明和解释。

API 快速示例

import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox';

export { Sandbox } from '@cloudflare/sandbox';

type Env = {
  Sandbox: DurableObjectNamespace<Sandbox>;
};

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // 预览 URL 所需
    const proxyResponse = await proxyToSandbox(request, env);
    if (proxyResponse) return proxyResponse;

    const url = new URL(request.url);
    const sandbox = getSandbox(env.Sandbox, 'my-sandbox');

    // 执行 Python 代码
    if (url.pathname === '/run') {
      const result = await sandbox.exec('python3 -c "print(2 + 2)"');
      return Response.json({ output: result.stdout, success: result.success });
    }

    // 处理文件
    if (url.pathname === '/file') {
      await sandbox.writeFile('/workspace/hello.txt', 'Hello, Sandbox!');
      const file = await sandbox.readFile('/workspace/hello.txt');
      return Response.json({ content: file.content });
    }

    return new Response('尝试 /run 或 /file');
  }
};

文档

📖 完整文档

• 入门指南 - 分步教程
• API 参考 - 完整的 API 文档
• 指南 - 执行命令、管理文件、暴露服务
• 示例 - AI 代理、数据分析、CI/CD 流水线

核心特性

• 安全隔离 - 每个沙箱都在独立的容器中运行
• 原生边缘 - 运行在 Cloudflare 的全球网络上
• 代码解释器 - 执行 Python 和 JavaScript，并获得丰富的输出
• 文件系统访问 - 读取、写入和管理文件
• 命令执行 - 运行任意命令，并支持流式处理
• 预览 URL - 使用公共 URL 暴露服务
• Git 集成 - 直接克隆仓库

贡献

我们欢迎社区贡献！请参阅 CONTRIBUTING.md，了解以下内容的指导原则：

• 设置开发环境
• 创建拉取请求
• 代码风格和测试要求

开发

此仓库包含 SDK 的源代码。快速入门：

# 克隆仓库
git clone https://github.com/cloudflare/sandbox-sdk
cd sandbox-sdk

# 安装依赖
npm install

# 运行测试
npm test

# 构建项目
npm run build

# 类型检查和代码格式化
npm run check

示例

请参阅 examples 目录，获取完整的可运行示例：

• 最小示例 - 从这里开始：执行命令、读写文件
• 代码解释器 - 为 Workers AI 上的 gpt-oss 提供一个 Python REPL
• Claude Code - 在任何仓库上无头运行 Claude Code
• OpenAI 代理 - 为 OpenAI 代理 SDK 提供 Shell 和 Editor 工具
• OpenCode - 将 OpenCode 的 Web UI 或 SDK 放置在沙箱中
• TypeScript 验证器 - 在沙箱中使用 npm 构建，并在 isolates 中执行

当前状态

Beta - SDK 处于积极开发中。API 在 v1.0 发布前可能会发生变化。

许可证

Apache License 2.0

链接

• 文档
• GitHub 问题
• 开发者 Discord
• Cloudflare 开发者

Cloudflare Sandbox SDK 快速上手指南

Cloudflare Sandbox SDK 允许你在 Cloudflare 的全球边缘网络上构建安全、隔离的代码执行环境。它非常适合用于 AI 代码执行、交互式开发环境、数据分析平台以及需要安全运行不可信代码的应用场景。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

1. Node.js: 版本需为 16.17.0 或更高。
   • 国内开发者建议使用 Node.js 国内镜像 进行安装。
2. Docker: 必须在本地运行 Docker 引擎（SDK 本地测试依赖容器）。
   • 请参考 Docker 官方安装指南 或配置国内加速源。
3. Cloudflare 账号: 如果计划部署到生产环境，需要注册 Cloudflare 账号。

安装步骤

使用官方提供的最小化模板快速创建新项目：

npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal
cd my-sandbox

提示：如果你在国内遇到 npm 下载速度慢的问题，可以临时切换镜像源： npm config set registry https://registry.npmmirror.com

基本使用

1. 本地运行与测试

启动开发服务器。首次运行时会自动构建 Docker 容器（约需 2-3 分钟），后续运行速度将显著提升。

npm run dev

服务器启动后（默认端口 8787），你可以测试以下端点：

• 执行 Python 代码:

  curl http://localhost:8787/run
  

• 文件操作测试:

  curl http://localhost:8787/file
  

2. 核心代码示例

以下是如何在 Worker 中调用 Sandbox API 执行命令和管理文件的最小化示例：

import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox';

export { Sandbox } from '@cloudflare/sandbox';

type Env = {
  Sandbox: DurableObjectNamespace<Sandbox>;
};

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // 处理预览 URL 所需的代理逻辑
    const proxyResponse = await proxyToSandbox(request, env);
    if (proxyResponse) return proxyResponse;

    const url = new URL(request.url);
    // 获取沙箱实例
    const sandbox = getSandbox(env.Sandbox, 'my-sandbox');

    // 示例 1: 执行 Python 代码
    if (url.pathname === '/run') {
      const result = await sandbox.exec('python3 -c "print(2 + 2)"');
      return Response.json({ output: result.stdout, success: result.success });
    }

    // 示例 2: 文件读写操作
    if (url.pathname === '/file') {
      await sandbox.writeFile('/workspace/hello.txt', 'Hello, Sandbox!');
      const file = await sandbox.readFile('/workspace/hello.txt');
      return Response.json({ content: file.content });
    }

    return new Response('Try /run or /file');
  }
};

3. 部署到生产环境

完成开发后，使用 Wrangler 将 Worker 和容器部署到 Cloudflare 全球网络：

npx wrangler deploy

注意：首次部署后，基础设施可能需要 2-3 分钟的预热时间，之后即可正常接收请求。