boxd
最后更新 查看 Markdown 源文件
boxd 适配器将已初始化的 boxd Box（来自 @boxd-sh/sdk）适配为 Flue 的沙箱接口。当智能体需要由提供商支持的、具有文件系统和 shell 行为的 Linux 虚拟机，而非轻量级的默认工作区时，可以使用它。
快速开始
使用 boxd 蓝图为现有 Flue 项目添加由提供商支持的 Linux 虚拟机沙箱能力。在终端或你选择的编码智能体中运行以下命令：
flue add sandbox boxd概述
boxd 蓝图会在需要时安装 @boxd-sh/sdk，并在你的源码根目录下创建 sandboxes/boxd.ts。生成的适配器接受应用创建的 boxd Box；它不会创建、保留或删除虚拟机。
// flue-blueprint: sandbox/boxd@1
import { sandboxFromDriver } from '@flue/runtime';
import type { SandboxDriver, SandboxFactory, Sandbox, FileStat } from '@flue/runtime';
import type { Box as BoxdBox } from '@boxd-sh/sdk';
export interface BoxdAdapterOptions {
cwd?: string;
readyTimeoutMs?: number;
}
async function waitForReady(box: BoxdBox, timeoutMs: number): Promise<void> {
/* 轮询 box.exec(['true']) 直到虚拟机就绪或超时。 */
}
function shellQuote(value: string): string {
return `'${value.replace(/'/g, `'\\''`)}'`;
}
class BoxdSandboxDriver implements SandboxDriver {
constructor(private box: BoxdBox) {}
/* 适配 boxd 的直接文件读写操作。 */
/* 使用带引号的 shell 工具实现 stat、readdir、exists、mkdir 和 rm。 */
/* 通过 bash -lc 运行命令，原样传递 env 和 timeoutMs。 */
}
export function boxd(box: BoxdBox, options?: BoxdAdapterOptions): SandboxFactory {
let readyPromise: Promise<void> | undefined;
return {
async createSandbox(): Promise<Sandbox> {
const sandboxCwd = options?.cwd ?? '/home/boxd';
readyPromise ??= waitForReady(box, options?.readyTimeoutMs ?? 30_000);
await readyPromise;
const driver = new BoxdSandboxDriver(box);
return sandboxFromDriver(driver, sandboxCwd);
},
};
}将 boxd(box) 作为智能体的 sandbox 传入，会等待该虚拟机的 exec 端点就绪一次，然后通过 Flue 暴露其文件和 Linux shell。相对路径从 /home/boxd 解析，除非你设置了 cwd；命令超时以毫秒为单位，stat 验证 GNU 元数据输出，rm 会接收请求的递归和强制标志，而虚拟机的身份、凭据、网络、持久化和清理仍由应用管理。
配置
| 变量 | 用途 |
|---|---|
BOXD_API_KEY | 替代认证 — 当不使用短期令牌时，使用此变量向 boxd 进行认证。 |
BOXD_TOKEN | 替代认证 — 提供提供商支持的短期认证，替代 BOXD_API_KEY。 |
| 覀求 | 用途 |
|---|---|
| 一个 boxd 凭据 | 必需 — 使用 BOXD_API_KEY 或 BOXD_TOKEN 其中之一。 |
@boxd-sh/sdk 包 | 必需 — 创建适配为 SandboxFactory 的 Linux 虚拟机。 |
| 应用自有的生命周期 | 必需 — 创建、复用和删除虚拟机。 |
生成的适配器期望你的应用创建并拥有 boxd 虚拟机。它不会为你决定虚拟机的身份、保留或清理策略。
适用场景
当任务需要在隔离的提供商虚拟机中运行真实的 Linux 命令行为时，选择 boxd，特别是当每个工作区或智能体实例使用独立虚拟机是你应用设计的一部分时。
在跨会话或租户复用虚拟机之前，请定义身份、授权、出口流量、密钥和清理策略。会话持久化仍由 Flue 会话存储单独控制。