Cloudflare Sandboxes 实操：给 Agent 一台随起随停的 Linux 云电脑（Durable Object 调度 + container API）

# 创建 Worker 项目（TypeScript，不自动部署、不初始化 git）
npm create cloudflare@latest -- sandbox-linux --category=hello-world --type=hello-world --lang=ts --no-deploy --no-git --no-agents

# 进入项目目录
cd sandbox-linux

官方脚手架一条命令生成最小 Worker 项目，参数里 --no-deploy --no-git 让你保留对部署与版本控制的主动权。Wrangler 要求 Node 16.17.0 或更高，官方建议用版本管理器避免权限问题。生成后先看一眼目录结构：wrangler.jsonc 是配置中心，src/index.ts 是即将改写的入口。接下来两步分别动这两个文件，把「Hello World」改造成「能起 Linux 容器的沙箱」。

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "sandbox-linux",
  "main": "src/index.ts",
  // 改成当天的日期
  "compatibility_date": "2026-10-01",
  "observability": { "enabled": true },
  "upload_source_maps": true,
  "containers": [
    {
      "class_name": "MyContainer",
      "scheduling_policy": "durable_object"
    }
  ],
  "durable_objects": {
    "bindings": [
      { "class_name": "MyContainer", "name": "MY_CONTAINER" }
    ]
  },
  "exports": {
    "MyContainer": {
      "type": "durable-object",
      "storage": "sqlite"
    }
  }
}

配置里三个块要一起看懂：containers 声明哪个类管容器，并指定 durable_object 调度策略（新架构的核心，让 DO 在运行时代码里决定镜像与规格）；durable_objects.bindings 把 MyContainer 类绑定为名为 MY_CONTAINER 的环境绑定，Worker 里通过 env.MY_CONTAINER 访问；exports 声明该 DO 类使用 SQLite 存储。官方示例的 compatibility_date 写的是示例当天日期，你实际配置时写自己的当天日期即可，不必照抄。

// src/index.ts
import { DurableObject } from "cloudflare:workers";

export class MyContainer extends DurableObject {
  async exec(argv) {
    const container = this.ctx.container;
    if (!container) {
      throw new Error("The container binding is not configured");
    }

    if (!container.running) {
      container.start({
        // Debian Trixie，自带 Node.js 24
        image: "cloudflare/debian-trixie",
        // 让实例常驻以便接受后续命令
        entrypoint: ["sleep", "infinity"],
        // 禁止沙箱内命令访问公网
        enableInternet: false,
      });
    }

    const process = await container.exec(argv);
    const output = await process.output();
    return {
      stdout: new TextDecoder().decode(output.stdout),
      exitCode: output.exitCode,
    };
  }
}

export default {
  async fetch(request, env) {
    const { argv } = await request.json();
    const sandbox = env.MY_CONTAINER.getByName("sandbox");
    return Response.json(await sandbox.exec(argv));
  },
};

这段官方示例浓缩了三个最佳实践。惰性启动：每次 exec 前检查 container.running，没在跑才 start()——648 毫秒的启动速度让「用时再开」比「预热保活」更划算，也省掉了闲置容器的费用。参数透传：Worker 把请求体里的 argv 数组直接交给 container.exec，不在代码里拼命令字符串，天然规避了命令注入的经典错误（谁可控的输入拼进 shell 谁出事）。网络默认关闭：enableInternet: false 让沙箱内代码出不了公网，Agent 生成的代码再离谱也摸不到外部世界。需要出网时（例如要装依赖）再按官方网络文档按需放开并配代理。

# 生成绑定类型（读取 src 里的 MyContainer 类）
npx wrangler types

# 本地开发：容器实例跑在本机 Docker 里
npx wrangler dev

# 前置条件：
#   - Docker 已安装且正在运行
#   - Wrangler 4.141.0 或更高版本
#     （本地拉起 cloudflare/debian-trixie 镜像所需）

wrangler types 让 env.MY_CONTAINER 带上正确类型，TypeScript 项目的必需步骤。wrangler dev 的行为值得说明：本地开发时容器实例跑在你本机的 Docker 里，所以 Docker 必须先启动；这也意味着本地与线上的微虚拟机环境高度一致，联调结果可信。版本要求别忽略——旧版 Wrangler 本地拉不起 cloudflare/debian-trixie 镜像，报错先查版本。

curl http://localhost:8787 --request POST \
  --json '{"argv":["uname","-a"]}'

# 预期返回：
#   JSON 里 "exitCode": 0
#   stdout 以 "Linux" 开头
#   （完整内容含内核版本与架构信息）

# 再试一条更实用的：
#   {"argv":["node","-v"]}
#   应返回 Node.js 24.x 的版本号

这条 curl 触发的完整链路是：Worker 收到 POST → env.MY_CONTAINER.getByName("sandbox") 定位到对应 DO → DO 发现容器未运行 → 以 debian-trixie 镜像启动 Linux 微虚拟机 → 执行 uname -a → 输出经 TextDecoder 转回 JSON。看到 exitCode: 0 和以 Linux 开头的 stdout，说明整条「HTTP 请求 → DO → 容器 → 命令 → 输出」链路全部打通。接下来把它变成真正的 Agent 工具只需两小步：在 Worker 里加一层鉴权，再把 argv 的来源从你的 curl 换成 Agent 的工具调用。官方还提供了「Build a coding agent runner」指南与 sandbox-sdk 仓库里的 minimal 模板（自带 Dockerfile、按 URL 名字隔离沙箱、文件读写），照着扩展即可。

# 1) 快照（public beta）：
#    把工作区文件状态保存，之后的新实例
#    可从快照恢复——Agent 跨会话接着干
#    官方 Lifetime 文档说明快照带回哪些文件

# 2) 按需出网：
#    enableInternet: false 是默认姿态；
#    需要装依赖时在官方网络指南的
#    凭证/代理框架内放开，凭据不出 Worker

# 3) 部署语义（官方 Lifetime 文档）：
#    wrangler deploy 不会替换正在运行的实例；
#    实例保留其启动时的镜像直到代码让它停止，
#    下一次由 DO 启动时才用新镜像

生产化要过三道认知。快照解决「Agent 的文件能不能活到明天」：把工作区状态存下来、新实例从快照恢复，长任务与多轮会话才有连续性；它同时是评测场景的利器——几百个沙箱从同一快照出发、跑完重置，状态严格一致。出网的正确姿势不是全局打开，而是按需放行加凭证代理：凭据留在 Worker，沙箱通过你的代理拿资源，泄漏面最小。部署语义最反直觉：wrangler deploy 不会重启在跑的实例，运行中的沙箱继续用旧镜像干活——这是刻意设计（Agent 不该在任务中途被换环境），灰度与回滚都变成「下一次 start 用什么镜像」的代码决策。理解这三条，沙箱才算真正接管了你的 Agent 执行层。