Cloudflare Sandbox SDK 指南

GA 2026.04

安全隔离的代码执行环境

官方文档

专为 AI Agent、代码解释器和开发者工具设计。提供独立、持久的 Linux 容器环境，运行不受信任的代码而不会影响基础设施。像操作“云端小电脑”一样简单。

AI Agent 代码执行数据分析/图表生成云端 IDE CI/CD 自动化

毫秒级启动

远快于传统 VM，冷启动几乎无感，完美适应按需触发的 AI 任务。

零信任强隔离

独立的容器边界，安全运行 LLM 生成的或用户提交的不受信任代码。

持久化会话

同一个 Sandbox ID 复用环境，保持文件系统和进程状态，空闲自动休眠。

边缘全球部署

部署在 Cloudflare 全球网络，极致低延迟，自动弹性缩放。

Workers AI 集成

无缝接入 AI 工作流，让大语言模型直接调用 Sandbox 解释并执行代码。

全功能交互 API

支持 Shell、文件操作、后台进程暴露及基于 WebSocket 的实时 PTY 终端交互。

快速开始与代码模板

1. 初始化项目

bash

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

2. 绑定配置 (wrangler.toml)必填项

toml

name= "my-sandbox-worker"
main= "src/index.ts"
compatibility_date= "2026-04-13"

# 声明并绑定 Sandbox 资源到 Worker 环境
[[sandbox]]
binding= "Sandbox"

3. 核心 API 示例库

typescript - 代码解释器

import { getSandbox } from "text-green-400">'@cloudflare/sandbox';
export { Sandbox } from "text-green-400">'@cloudflare/sandbox';

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const sandbox = getSandbox(env.Sandbox, "text-green-400">'user-123');

    // Create a Python execution context
    const ctx = await sandbox.createCodeContext({ language: "text-green-400">'python' });

    // Execute Python code with automatic result capture
    const result = await sandbox.runCode("text-green-400">`
import pandas as pd
data = {"text-green-400">'product': ["text-green-400">'A', "text-green-400">'B', "text-green-400">'C'], "text-green-400">'sales': [100, 200, 150]}
df = pd.DataFrame(data)
df["text-green-400">'sales'].sum()  # Last expression is automatically returned
`, { context: ctx });

    return Response.json({
      result: result.results?.[0]?.text,
      logs: result.logs
    });
  }
};

4. 测试与部署

bash

# 本地测试 (依赖本地 Docker)
npm run dev

# 部署到 Cloudflare 全球边缘网络
npx wrangler deploy

核心功能速览

命令执行：流式输出、超时控制、富文本输出
文件管理：读写、目录操作、Git Clone
后台进程：暴露服务并生成 Preview URL
浏览器终端：支持 xterm.js 实时 PTY 交互
快照 & 存储：挂载 R2/S3 或使用会话快照恢复

极致省钱计费

~ $0.00002 / vCPU-second

Active CPU 计费模式：仅对实际使用的 CPU 周期收费，空闲（Idle）状态几乎不产生费用。极大降低间歇性 AI 任务成本。

注意事项 & 限制

• 必须开启 Workers Paid 计划。
• 本地开发依赖 Docker（需 Node.js ≥ 16.17）。
• 网络出口代理：Sandbox 默认无法直连外部，需通过 Outbound Workers 代理防滥用。
• 非持久化内存：未挂载存储或快照的情况下，重启后文件丢失。
• 无桌面 GUI：主打 headless，不适合重度图形/GPU渲染任务。