Cloudflare Sandbox

Cloudflare Sandbox 使用 @cloudflare/sandbox 为部署在 Cloudflare 上的 Flue 应用提供容器支持的 Linux 环境。此集成是平台原生的：它不是 Node 目标应用的适配器模块。

快速开始

使用 Cloudflare Sandbox 蓝图为现有 Flue 项目添加容器支持的 Linux 沙箱能力。

将此提示复制到你的编码智能体中。智能体获取的蓝图是一个实现指南，而非安装程序 —— 智能体会读取它，然后检查并修改你的项目。它可能会：

• 安装 @cloudflare/sandbox。
• 在 Flue 源码根目录添加或更新 cloudflare.ts。
• 将 Sandbox Durable Object 绑定和新的迁移条目添加到 wrangler.jsonc。
• 创建或更新容器 Dockerfile。
• 修改你的 Flue 智能体，使用 getSandbox(...) 获取沙箱并使用 useSandbox(...) 附加它。
• 检查现有项目结构，避免覆盖不兼容的设置。

如果你的项目当前目标是 Node，蓝图会在将整个项目迁移到 Cloudflare 目标之前停下来与你确认 —— Cloudflare Sandbox 只能在 Worker 内部运行。

开始之前，检查两个前置条件：

• Workers 付费计划。 Cloudflare Sandbox 运行在 Containers 上，这是 Workers 的付费功能。参见 Sandbox 定价。
• 本地开发需要 Docker。 vite dev 会在本地构建并运行沙箱容器镜像，因此 Docker 守护进程必须安装并运行。已部署的 Worker 不需要 Docker。

概述

Cloudflare Sandbox 是 Cloudflare 目标集成，而非生成的适配器。在 Cloudflare 目标项目中，蓝图会安装 @cloudflare/sandbox；智能体函数使用 getSandbox(...) 获取绑定的 Durable Object，使用 Flue 的 cloudflareSandbox(...) 封装它，并使用 useSandbox(...) 附加它。

'use agent';
import { env } from 'cloudflare:workers';
import { type AgentProps, useModel, useSandbox } from '@flue/runtime';
import { cloudflareSandbox } from '@flue/runtime/cloudflare';
import { getSandbox } from '@cloudflare/sandbox';

interface Env {
	Sandbox: DurableObjectNamespace;
}

export function CodingAgent({ id }: AgentProps) {
	useModel('anthropic/claude-opus-4-7');
	const { Sandbox } = env as unknown as Env;
	useSandbox(cloudflareSandbox(getSandbox(Sandbox, id)));
}

蓝图还会从源码根目录的 cloudflare.ts 导出 Sandbox，添加其 Durable Object 绑定、新的迁移条目及其容器声明到 wrangler.jsonc，并创建项目根目录的 Dockerfile，其镜像标签与安装的包版本匹配。智能体的 shell 和文件操作在按智能体实例 ID 标识的容器支持沙箱中运行。Cloudflare 的直接删除 API 不暴露递归或强制控制，因此 cloudflareSandbox() 通过在容器中运行 rm 来实现这两个选项，与 Node 的 fs.rm 语义匹配。Node 目标项目必须先迁移到 Cloudflare 目标才能使用此集成。

配置

Cloudflare Sandbox 需要 Worker 部署、Durable Object/容器配置和容器镜像。将依赖添加到 Cloudflare 目标项目，并从你的 Cloudflare 部署模块导出其 Durable Object 类：

// <source-root>/cloudflare.ts
export { Sandbox } from '@cloudflare/sandbox';

在 Wrangler 配置中声明沙箱绑定，然后使用 cloudflareSandbox(...) 封装 getSandbox(...) 返回的 RPC 存根，并将其传递给智能体：

import { env } from 'cloudflare:workers';
import { getSandbox } from '@cloudflare/sandbox';
import { type AgentProps, useModel, useSandbox } from '@flue/runtime';
import { cloudflareSandbox } from '@flue/runtime/cloudflare';

interface Env {
	Sandbox: DurableObjectNamespace;
}

export function Assistant({ id }: AgentProps) {
	useModel('anthropic/claude-sonnet-4-6');
	const { Sandbox } = env as unknown as Env;
	useSandbox(cloudflareSandbox(getSandbox(Sandbox, id)), { cwd: '/workspace' });
}

适用场景

当 Cloudflare 上的智能体需要 git、包安装、原生二进制文件或其他 Linux 工具时，使用 Cloudflare Sandbox。当持久化工作区配合面向工作区的操作就足够，且不需要 Linux 工具链时，优先使用 Cloudflare Shell。

将网络出口、挂载数据、凭据和副作用视为应用安全决策。参见沙箱和在 Cloudflare 上部署。