Cloudflare沙箱（Sandboxes）正式全面商用

当智能体像开发者一样工作时，要高效完成这些任务往往需要一套完整的运行环境，目前不少开发者通过虚拟机或现有容器技术自行搭建方案，但过程中会遇到诸多难以解决的问题。Cloudflare已针对性解决了以上所有问题，让你无需重复踩坑。

为了让更多企业用上沙箱能力，今天Cloudflare正式宣布：Cloudflare沙箱（Sandboxes）与Cloudflare容器均已全面商用（GA）。

下面介绍沙箱近期的核心更新：

安全凭证注入：无需让智能体接触密钥，即可完成鉴权请求
伪终端（PTY）支持：为用户与智能体提供真实可用的终端环境
持久化代码解释器：开箱即用，支持智能体运行有状态的 Python、JavaScript、TypeScript 代码
后台进程与实时预览链接：便捷对接开发服务，实时验证代码改动
文件系统监听：智能体修改文件时，迭代开发效率大幅提升
快照功能：快速恢复智能体的编程会话状态
更高并发配额与活跃 CPU 计费：规模化部署智能体集群，无需为闲置算力买单

Cloudflare沙箱介绍

Cloudflare沙箱是依托Cloudflare容器打造的持久化、隔离运行环境。你只需通过名称调用沙箱：运行中则直接调用，未运行则自动启动，闲置时自动休眠，收到请求后即刻唤醒。通过 exec、gitClone、writeFile 等方法，即可通过代码便捷操控沙箱。

import { getSandbox } from “@cloudflare/sandbox”;
export { Sandbox } from “@cloudflare/sandbox”;

export default {
async fetch(request: Request, env: Env) {
// 按名称获取沙箱，按需自动启动
const sandbox = getSandbox(env.Sandbox, “agent-session-47”);

// 克隆代码仓库
await sandbox.gitCheckout(“https://github.com/org/repo”, {
targetDir: “/workspace”,
depth: 1,
});

// 运行测试套件，实时流式返回输出结果
return sandbox.exec(“npm”, [“test”], { stream: true });
},
};

只要使用相同的 ID，全球任意位置的后续请求，都能连接到同一个沙箱。

安全凭证注入

在智能体工作场景中，鉴权是最棘手的问题之一。Cloudflare常需要智能体访问私有服务，却不能将原始密钥直接交给不可信的智能体。

沙箱通过可编程出口代理，在网络层自动注入凭证，完美解决这一问题：沙箱内的智能体永远无法获取密钥，你还可自定义完整的鉴权逻辑。

class OpenCodeInABox extends Sandbox {
static outboundByHost = {
“my-internal-vcs.dev”: (request, env, ctx) => {
const headersWithAuth = new Headers(request.headers);
headersWithAuth.set(“x-auth-token”, env.SECRET);
return fetch(request, { headers: headersWithAuth });
}
}
}

真实终端，而非模拟环境

早期智能体系统大多将终端操作设计为 “请求 – 响应” 模式：执行命令→等待输出→将日志回填提示词→重复执行。这种方式虽可用，却不符合开发者的真实使用习惯。

人类开发者运行程序时，会实时查看输出流、中断进程、稍后重连继续操作，智能体也需要同款交互体验。

今年 2 月，Cloudflare上线了伪终端（PTY）功能：沙箱内的伪终端会话通过 WebSocket 代理，兼容 xterm.js。

仅需调用 sandbox.terminal 即可搭建后端服务：

// Worker：将 WebSocket 连接升级为实时终端会话
export default {
async fetch(request: Request, env: Env) {
const url = new URL(request.url);
if (url.pathname === “/terminal”) {
const sandbox = getSandbox(env.Sandbox, “my-session”);
return sandbox.terminal(request, { cols: 80, rows: 24 });
}
return new Response(“Not found”, { status: 404 });
},
};

前端通过 xterm 插件即可连接使用：

// 浏览器端：将 xterm.js 连接至沙箱终端
import { Terminal } from “xterm”;
import { SandboxAddon } from “@cloudflare/sandbox/xterm”;

const term = new Terminal();
const addon = new SandboxAddon({
getWebSocketUrl: ({ origin }) => `${origin}/terminal`,
});

term.loadAddon(addon);
term.open(document.getElementById(“terminal-container”)!);
addon.connect({ sandboxId: “my-session” });

如此一来，智能体与开发者均可通过完整伪终端，实时调试会话。

每个终端会话都拥有独立的 Shell、工作目录与环境变量，可像本地电脑一样开启多个终端；服务端会缓存输出内容，重连时自动回放遗漏信息。

支持状态记忆的代码解释器

针对数据分析、脚本编写、探索式开发场景，Cloudflare还提供了更高级的能力：持久化代码执行环境。
核心亮点是「持久化」。多数代码解释器会独立运行每一段代码，导致调用间状态丢失 —— 上一步定义的变量，下一步便无法读取。

而 Cloudflare 沙箱支持创建持久状态上下文，变量与导入内容会像 Jupyter 笔记本一样，跨调用保留：

// 创建 Python 上下文，状态在生命周期内持续保留
const ctx = await sandbox.createCodeContext({ language: “python” });

// 首次执行：加载数据
await sandbox.runCode(`
import pandas as pd
df = pd.read_csv(‘/workspace/sales.csv’)
df[‘margin’] = (df[‘revenue’] – df[‘cost’]) / df[‘revenue’]
`, { context: ctx });

// 二次执行：df 变量依然有效
const result = await sandbox.runCode(`
df.groupby(‘region’)[‘margin’].mean().sort_values(ascending=False)
`, { context: ctx, onStdout: (line) => console.log(line.text) });

// 返回结果包含 Matplotlib 图表、结构化 JSON、HTML 格式的 Pandas 表格

一键启动服务，生成公网预览链接

智能体完成开发后若能立刻展示成果，实用性会大幅提升。沙箱支持后台进程、服务就绪检测与预览链接，智能体无需中断对话，即可启动开发服务并分享实时预览链接。

// 以后台进程启动开发服务
const server = await sandbox.startProcess(“npm run dev”, {
cwd: “/workspace”,
});

// 等待服务真正就绪，而非盲目等待固定时长
await server.waitForLog(/Local:.*localhost:(\d+)/);

// 为运行中的服务分配公网预览链接
const { url } = await sandbox.exposePort(3000);

// 智能体可直接将该链接分享给用户
console.log(`Preview: ${url}`);

通过 waitForPort() 与 waitForLog()，智能体可依据程序真实运行信号编排任务，无需依靠 sleep(2000) 这类盲等操作。

文件系统实时监听，即时响应代码改动

现代开发流程均为事件驱动：保存文件→重新构建、修改配置→重启服务、更新测试→重新运行。

今年 3 月，Cloudflare上线了 sandbox.watch() 功能，基于 Linux 内核 inotify 机制，返回 SSE 事件流。

import { parseSSEStream, type FileWatchSSEEvent } from ‘@cloudflare/sandbox’;

const stream = await sandbox.watch(‘/workspace/src’, {
recursive: true,
include: [‘*.ts’, ‘*.tsx’]
});

for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
if (event.type === ‘modify’ && event.path.endsWith(‘.ts’)) {
await sandbox.exec(‘npx tsc –noEmit’, { cwd: ‘/workspace’ });
}
}

这一基础能力，极大拓展了智能体的应用边界：能够实时监听文件系统的智能体，可与人类开发者一样，拥有完整的开发反馈闭环。

快照功能：秒级唤醒，快速恢复工作状态

想象人类开发者的工作场景：克隆仓库、安装依赖、编写代码、提交 PR，随后合上电脑等待代码审核；恢复工作时，打开电脑即可继续之前的进度。

若智能体在普通容器平台复刻这一流程，便会遇到难题：如何快速恢复状态？一直运行沙箱会产生闲置成本，从镜像全新启动又要等待漫长的克隆与安装过程。

Cloudflare的解决方案是快照功能，该功能将在未来几周内全面上线。

快照会保存容器的完整磁盘状态、系统配置、已安装依赖、修改文件、数据文件等全部信息，后续可快速还原。

你可配置沙箱在休眠时自动创建快照：

class AgentDevEnvironment extends Sandbox {
sleepAfter = “5m”;
persistAcrossSessions = {type: “disk”}; // 也可指定单独目录
}

也可通过代码手动创建、恢复快照，适用于任务断点保存与会话分叉场景。例如需要并行运行四个智能体实例，可基于同一状态快速启动四个沙箱。

class AgentDevEnvironment extends Sandbox {}

async forkDevEnvironment(baseId, numberOfForks) {
const baseInstance = await getSandbox(baseId);
const snapshotId = await baseInstance.snapshot();

const forks = Array.from({ length: numberOfForks }, async (_, i) => {
const newInstance = await getSandbox(`${baseId}-fork-${i}`);
return newInstance.start({ snapshot: snapshotId });
});

await Promise.all(forks);
}

快照存储在账号的 R2 对象存储中，具备高持久性与全球就近访问能力；R2 分层缓存机制，可让全球所有区域实现沙箱快速恢复。

未来版本中，Cloudflare还将支持内存状态快照，运行中的进程可精准恢复至休眠前状态，终端与编辑器也会还原至关闭前的界面。

在快照正式上线前，你可使用备份与恢复功能：同样依托 R2 存储目录，性能虽不及虚拟机级快照，但相比从零重建会话，速度提升十分显著。

举个例子：启动沙箱→克隆 axios→安装依赖需 30 秒，从备份恢复仅需 2 秒。

敬请期待快照功能的正式发布。

自发布以来，Cloudflare持续扩容。标准定价方案用户，目前可同时运行：