# @agent-relay/sandbox 中文文档

规范地址：https://npmcn.com/package/%40agent-relay/sandbox/

版本：0\.1\.16
npm 元数据更新时间：2026-09-16T14:45:20.947Z
中文译文更新时间：2026-11-06T08:35:48.626Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agent-relay/sandbox
原文对照：https://npmcn.com/package/%40agent-relay/sandbox/?lang=original
项目主页：https://github.com/AgentWorkforce/sandbox#readme
源码仓库：https://github.com/AgentWorkforce/sandbox

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，187 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：e2b \>=2\.35\.0 \<3\.0\.0，modal \>=0\.9\.0 \<0\.10\.0，freestyle 0\.1\.63，microsandbox \>=0\.6\.11 \<0\.7\.0，@daytonaio/sdk \>=0\.180\.0 \<0\.206\.0，@vercel/sandbox \>=3\.0\.1 \<4\.0\.0，@aws-sdk/client-bedrock-agentcore \>=3\.1115\.0 \<4\.0\.0，@aws-sdk/client-bedrock-agentcore-control \>=3\.1115\.0 \<4\.0\.0
- 首次发布：2026-07-18T11:38:35.643Z
- 最新版本发布：2026-09-16T14:45:20.570Z
- 近 30 天下载量：3802（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

提供不可知的沙盒运行时间和代理工作量的管弦.

## 安装

```sh
npm install @agent-relay/sandbox
```

也可以使用：`pnpm add @agent-relay/sandbox`、`yarn add @agent-relay/sandbox`、`bun add @agent-relay/sandbox`

## README

# @ agent-relay/ sandbox (英语)

提供不可知的沙盒运行时间和代理工作量的管弦.

写代码的探员需要找个地方运行 此软件包提供了一个单 几个沙盒提供者执行的运行时端口,加上管弦 推动沙盒通过工作量的层: 启动它,放入文件, 运行命令,流结果返回,并拆掉.

端口的要点是 管弦乐层没有提供商 知识。 突袭提供者是适配器的改变,而不是呼叫器的改变.

> **状况:1.0前.** 公众API仍然可能在 `1.0.0` 释放.

## 安装

```bash
npm install @agent-relay/sandbox
```

## 运行您的第一个工作量

对于 E2B 沙盒,也安装 `e2b`设置 `E2B_API_KEY` 在您的申请中 环境,并保存为 `hello.mjs`数字 :

```js
import { withSandbox } from "@agent-relay/sandbox/core";
import { E2BSandboxRuntime } from "@agent-relay/sandbox/e2b";

const apiKey = process.env.E2B_API_KEY;
if (!apiKey) throw new Error("Set E2B_API_KEY before running this example");

const result = await withSandbox({
  runtime: new E2BSandboxRuntime({ apiKey, template: "base" }),
}, (sandbox) => sandbox.run("echo hello", { timeoutMs: 10_000 }));

console.log(result.output);
if (result.exitCode !== 0) process.exitCode = 1;
```

运行 `node hello.mjs`。 。 。 . `withSandbox` 创建一个沙盒,运行你的回调,和 尝试清理回调是否成功或丢出。 两者都有保留 如果工作量和清理失败, 错误 。 使用 `createSandbox` 从同 需要明确输入点时 `run` 编号 : `destroy` 控制系统。 双方接受 相同的提供者运行时间; 更改提供者更改适配器配置 . 这些帮助者不会重试不确定的创建或提供过程后的恢复 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}死吗? 供应商收费和限额仍然适用.

### 从一个沙盒到软件厂

如果您要自己构建执行层, 请使用此软件包 。 当你 需要发现问题、多种编码代理、审查、公关出版物和 合并闸门, [软件园](https://github.com/AgentWorkforce/software-garden) 提供该工作流程。 它的起点是 `npm install @agent-relay/factory` 接下来是 `factory init` 在目标仓库中; 花园检查其中继器和 设置时寄存器访问先决条件 .

托管的AgentWorkforce集成公司可自主核算 那个工厂 SDK仍然可用于自己的供应商账户,并且确实 不需要Workforce代理登录。 见 [建立融合合同](https://npmcn.com/package/%40agent-relay/sandbox/docs/setup.md) 对于边界,一个主机“与代理Workforce连接”的经验可以执行.

### 提供者账户设置

`@agent-relay/sandbox/setup` 用品 `createProviderSetup(backend)` 为信任 应用程序后端。 设置是明确的( A)`prewarm`(三); `status` 财务报告和审定财务报表 `hasAvailableCredentials` 只读准备。 传递到路由器或 改为 `createSandbox` 编号 : `withSandbox` 作为可选的准备门。 没有 返回账户证书或自动创建提供者账户 沙盒发射. 提供了后端执行及其上载UI ; 此软件包不主张一个直播主机连接.

### 托管的 AgentWorkforce 沙盒( 私人预览)

这个 `@agent-relay/sandbox/hosted` 切入点是一个提供者中立的外观,用于 伴云会场的终点。 只是私人审查,不是 已经部署或普遍可以使用。 见 [主机指南](https://npmcn.com/package/%40agent-relay/sandbox/docs/hosted.md) 最终使用五行及其明确的部署要求.

## 提供者适配器

提供方 SDK 是对等依赖: 安装您打算使用的 。 A 类 只运行本地沙盒的消费者不需要远程供应商SDK. 没有发布 JavaScript SDK 的提供者的适配器 直接且完全不增加依赖性;它们可注射 `fetch` 换句话说.

导入提供者中性 API 和从单独的入口导入选中的适配器 :

```ts
import { SandboxOrchestrator } from "@agent-relay/sandbox/core";
import { DaytonaRuntime } from "@agent-relay/sandbox/daytona";
```

供应商的入境点是 `agent37`, (中文(简体) ), `agentcore`, (中文(简体) ), `daytona`, (中文(简体) ), `e2b`, (中文(简体) ), `freestyle`, (中文(简体) ), `local`, (中文(简体) ), `microsandbox`, (中文(简体) ), `modal`,以及 `vercel`。每个点 拥有枪管,所以捆绑机不需要解决其他可选的提供者SDK. 词根 `@agent-relay/sandbox` 桶仍然输出 完整的历史 用于兼容的表面,但新运行时间导入应当使用 `core` 加一个 提供子路径.

导出地图使用 `./* -> ./dist/*/index.js` 而不是列举今天 供养者. 要安全添加另一个提供者, 请添加 `src/<provider>/index.ts` 联合国 并宣布其SDK为可选对等器。 包裹 合同测试需要每个运行时目录( 以及每个可选的同行所有者) 装入包装的烟雾测试验证这些桶 在不安装任何可选的同位素的情况下, 进行船舶和导入 .

### 供应商的限制

每个适配器继承其供应商SDK的要求,它们并非全部 与本套件相同:

| 适配器 | 同伴依赖关系 | 超过本套装的要求 |
| --- | --- | --- |
| `DaytonaRuntime` | `@daytonaio/sdk` 0.180-0.205 (中文(简体) ) | —— 说 |
| `E2BSandboxRuntime` | `e2b` | —— 说 |
| `MicrosandboxRuntime` | `microsandbox` | **节点.js 22+**,一个针对平台的本地附加物(macOS arm64, Linux x64/arm64, Windows x64/arm64),以及——用于其 `local` 后端 — 硬件虚拟化: Linux 上的 KVM, macOS 上的 Apple Silicon, 或 WHP 上的 Windows 10+ |
| `LocalSandboxRuntime` | —— 说 | 可到达的本地沙盒服务 |

包裹本身保留了20层的节点 因为一个从未触及的消费者 微软箱适配器不会装入 SDK : 它最初是懒惰地导入的 ,并且报告负载失败时往往受到制约 解释一下.

### 微沙盒能力对后端敏感

`MicrosandboxRuntime.capabilities` 是从后端衍生出来的实例 有义务,而不是作为一个单一的全过程常数报告:

| 能力 | `local` | `cloud` | 为什么 |
| --- | --- | --- | --- |
| `snapshots` | `true` | `false` | 一个快照是一个主机本地的文物:安装的SDK的打字描述 `Snapshot` 作为磁盘上的文物 解决一个 `~/.microsandbox/snapshots/<name>/`。这个适配器从调用主机中消耗了这样的文物,并且从不传输,所以一个针对远程后端发布的创建没有解决的余地。 配置 `snapshot` 在任何SDK呼叫之前,在构造器中拒绝使用云后端. |
| `isolation` | `'strong'` | `'unknown'` | 本地SDK在虚拟化能主机上用自有的来宾内核将一个微VM靴出,而已安装的软件包则表示需要自己,所以 `'strong'` 以某种可核查的东西为基础 此适配器观察并测量云后端的孤立度. |

两种值都描述此软件包的特性 **已设立**没有什么 提供者文档. `'unknown'` 不是弱者的同义词,也不是主张 保证是缺失的,这意味着这个一揽子计划没有建立, 因此,一个需要具体保证的打电话者必须自行决定 而非诵读未经证实的经典 `'strong'`。 。 。 .

云区域布局和资源执行同样没有代表 衡量事实。 自定义或已公布 **不支持端口**: SDK 构建器 曝光情况 `port()`编号 :`portBind()`,但该套件的目标没有 所以适配器从不叫他们 也从不暗示 可到达端口.

## 设计

两块,故意分开:

-   **运行时适配器** 实施一个小端口——发射、执行、文件传输, 撕毁——一个供应商.
-   **指挥家** 将工作量通过所给出的运行时间. 这是通用的 超过提供者的手柄类型 并且不知道任何 特定的提供者.

配置被注入,从未被烤入. 包船没有默认 模板、端点、主机名或证书:任何特定环境 是呼叫者提供的必要论据。 这样可以使用软件包 在环境之外,它从环境中取出,并保持证书处理 呼叫者属于它.

每个适配器还声明它真正支持什么而不是它支持什么 方法名称的含义. `resolveSandboxRuntimeCapabilities` 阅读该声明, 因此,一个呼叫者在前面学习一个提供者是否可以通过id重接到一个沙盒, 调查一个背景命令, 交回一个仍在启动的沙盒, 或搜索由 标签——而不是从运行时间的失败中发现答案.

### Daytona 重新开始恢复

`DaytonaRuntime.start()` 不只信任提供者国家过渡。 这个 sDK 沙盒再加水并运行一个有边框 `true` 后准备探测器 `start`, (中文(简体) ), 因为戴托纳可以报告 `STARTED` 当其工具箱执行守护进程仍保留时 无. 健康重启保留了相同的沙盒ID. 期间的失败 补水本身( 自动、 速率限制或网络) 并不是执行守护进程的证据 已经死了,所以它被宣传 as -is,从来没有触发替换.

当启动后准备状态探测器失败时,运行时间默认创建和证明 在删除无法使用的沙盒之前替换。 返回的手柄是 因此,可以建立一个新的 `id`呼唤者必须坚持 返回身份证明。 替换保存所配置的快照加提供者 标签、环境、生命周期、体积和网络设置,但非体积 旧沙盒中的文件系统更改不复制。 国人唤作: 更喜欢硬失败 而不是这种权衡 `recreateOnFailedStart: false`。 。 。 .

### E2B运行时间合同

`E2BSandboxRuntime` 执行外侧管弦乐端口和直播 `WorkflowRuntime` 表面:元数据/状态查取、重新附着、同步和 持续同步执行,上传/下载,家用指令解析, 暂停/ 恢复, 以及自有资源撕毁 。 它故意不暴露一个 由于 E2B 的公开创建调用等待运行, 解开发射方法 沙盒 沙盒 沙盒 沙盒 沙盒 其现场能力描述器也报告PTY和流出日志 不支持,因为这个适配器 既不暴露行为,即使 提供商SDK为他们提供了更低等的API.

适配器在创建、再连接和 同步使用; `sandboxLifetimeMs` 默认已配置的同步 运行预算.

同步跑总是带有明确的命令寿命上限,因为E2B—— 单在此处的提供者中——当字段为时,适用60秒的默认值 省略,而乐团省略 `timeoutMs` 在大多数执行者。 跑不动 因此使用调用器超时 `syncRunBudgetMs`,默认为 配置 `runBudgetMs` (30分钟,除非设定). 明确的呼叫超时 总是胜出,是唯一能把沙盒延伸过去的东西 `sandboxLifetimeMs`;隐含的预算从来没有.

同步会话ID是不可改变的一能键. 重试 将持久录取记录与 E2B 的流程列表进行校正,而不 删除会话目录或提交另一个副本。 仅待处理 当匹配的提供者进程存在时。 如果这个过程消失了 不发布其退出侧车,状态变为终端 `E2B_ASYNC_PROCESS_LOST_EXIT_CODE` (单位:千美元)`255`) (中文(简体) ).

### 代托纳电信设备

代托纳的"桑德博克"电线反应搭载了两个字段—— `sandboxClass` (单位:千美元) 沙盒的等级/等级)和 `warmPoolId` (设置为沙盒为无人认领) ——存在于低层次上 `@daytona/api-client` 不过,DTO 卖家 `@daytonaio/sdk`是因为 `Sandbox` 类不复制到 自己来. `DaytonaRuntime.getWireSupplement(handle)` 直接通过 sDK的低层 `sandboxApi`,相同的范围模式 `runtime.ts` 已经 用于去除生成.

这是一个狭窄的,故意的临时缺口,而不是SDK的叉: 其他被怀疑失踪的字段(`autoDestroyAt`, (中文(简体) ), `autoPauseInterval`, (中文(简体) ), `spot`) 已经上载公众 `Sandbox` 类别截至 `@daytonaio/sdk` 0.200.0-0.205.0——仅靠依赖就涵盖这些。 上游跟踪 [aytona/客户编号207](https://github.com/daytona/clients/issues/207) (前为: [192号](https://github.com/daytona/clients/pull/192)中添加 `spot` 也一样). 退休人员 `src/daytona/wire-supplement.ts` 一次 `processSandboxDto()` 副本 `sandboxClass`编号 :`warmPoolId` 和随后的 SDK 碰碰捡起这个.. `runtime.test.ts`是因为 `DaytonaRuntime smoke` 套房有一个 一旦发生负载回归测试失败 .

### 自由式运行时间合同

`FreestyleRuntime` 使用明确的 API 密钥、 主目录、 所有权名称 前缀和持久性政策。 它从来不读环境证书。 自由风格 所以标签搜索和暖租仍然保留 不支持;所有权和清理范围扩大到该定义下的碰撞安全名称 已配置前缀 。 已删除的列表行仅在提供者时被视为已消失 套装 `deleted: true`。 。 。 .

适配器会曝光缓冲执行,文件传输,再附加,自有资源 列出,并核实删除。 停止/启动方法是一种保守方法 探测器表面,但寿命周期仍未宣布,因为现场验证 账户无法创建持续 VM 。 PTY,快照,流体记录,叉子, 而永不放弃的行为 也同样不会被广告 没有必需的活 通过此软件包的公用端口验证.

官方SDK被隔离在下面 `src/freestyle/internal/`; 公开 配置和能力元数据不导入供应商类型。 所有创造, 查询、执行、生命周期和删除操作都有明确的期限。 见 [自由式适配符注释](https://npmcn.com/package/%40agent-relay/sandbox/docs/freestyle.md) 供养来源, 供应商的制约和能力证据.

### Vercel Sandbox 运行时合同

`VercelSandboxRuntime` 使用明确的符号、团队标识、项目标识、所有权 名称前缀和主目录,并传递每个 SDK 呼叫的证书 销售商自己的环境和OAuth倒计时器永远无法提供 操作员的身份.

Vercel沙盒通过它的 **名称**而不是一个不透明的id,所以 `RuntimeHandle.id` 携带名称, 配置的前缀为真实 所有权边界: 停止、 开始和删除 . `Sandbox.list` 支持服务器侧 `namePrefix` 财务报告和审定财务报表 `tags` 过滤器,所以标签 搜索是真正的搜索, 但每行都会根据请求重新检查 标记正在处理中, 因为一个被忽略的服务器过滤器会递还 别人的沙盒 作为暖租. `getById` 已执行 `list` 而不是说 `Sandbox.get`,它恢复和计费 沙盒作为一种副作用.

删掉通过缺席进行验证,再用同名词出现一行 一个不同的 `createdAt` 证明我们的沙盒不见了 一个幸存者。 验证失败, 保留注册, 故要保留清理 可重试. `acquire()` 返回一个 `AsyncDisposable` 页:1 `await using` 瞄准镜.

命令为 `sh -c` 与 `cwd` 财务报告和审定财务报表 `env` 通过提供者字段,所以 没有调用器值被拼接成命令字符串 。 每一次行动都带有 在绝对期限内 `retryDeadlineMs` 横跨 SDK 的天花板 内部复试.

温暖的租赁,生命周期,PTY,快照,流出日志,叉子,并被验证 全部清理完毕 `false` 等待现场证据;永不解决 因为每个Vercel沙盒都有终止期限 官员 SDK被隔离在下面 `src/vercel/internal/`。见 [vercel 适配符注释](https://npmcn.com/package/%40agent-relay/sandbox/docs/vercel.md) 供养来源, 能力证据,以及活性-CPU-对活性-时钟定价分析.

能力在结构上也被宣布。 PTY和快照决心 `"not-exposed"` 真实的SDK 无法通过这个港口 所以不行 现场探测器可以促进的 `lifetime` 决定: `"deadline"`, (中文(简体) ), vercel沙盒的定点理由 从来没有一级. `filesystem` 实值 故意离开 `"unknown"`:耐久性为每英寸配置 (单位:千美元)`persistent`),幸存的一站/再站是相同的往返 `lifecycle` 还在等待现场证明.

### 模式运行时间合同

`ModalRuntime` 带一个明显的 Modal **符号对** (单位:千美元)`tokenId` 财务报告和审定财务报表 `tokenSecret` —— Modal 不使用单个无记名密钥, App 名称, 图像 标签、家目录和所有者名前缀。 它从来不读环境 证书或本地 Modal 简介.

一个Modal Sandbox是一个App的孩子,由一幅图像构建,它有一个 **最大寿命, 提供方终止** ——SDK的自已 默认为5分钟. `maxLifetimeMs` 因此需要配置和 总是被明确发送. `createTimeoutSeconds` 打开 `launch` 是一个截止时间 创作的呼唤,被刻意不传递到那个生命中.

Modal显示一个沙盒没有停止/启动; `terminate` 是唯一的生命周期 过渡,它是终端. `start` 财务报告和审定财务报表 `stop` 缺席,而不是 没有 -ops,和 `lifecycle` 被永久宣布为虚假。 Async Exec同样是 未执行 : Modal 无法用 id 重新解决运行中的执行, 因此 `startScript`编号 :`getScriptStatus`编号 :`getScriptLogs` 三重奏被完全省略 被半个支持.

所有权在Modal的本地服务器端标签上,而不是在命名上 公约。 每个沙盒都贴着所有者标签 上面的每个检查过滤器 服务器端,以及重新附加和删除两者都重新检查。 温暖的租赁是 使用真实的标签过滤器执行,但一直未申报,直到直播 探测器证实了 供应商中存在快照、卷数、PTY和地道 并且被记录,但是没有广告 因为这个软件包的端口暴露 没有操作他们.

最后的区别现在在结构上而不是在说教中加以阐述。 这个 适配器声明 `declaredCapabilityModes`,所以PTY和快照决心 `"not-exposed"` ——关于这个包裹的端口的事实 `isPendingEvidence()` 报告是不可移动的,而不是一无所有 `false` 后一金丝雀可能读作 仅仅是未经证实. `lifetime` 决定: `"deadline"`,这是 一个Modal沙盒的结构性原因 永远不能被忽略 输出为 `"buffered"`: Modal溪流,适配器排出. 暖和的租房是故意的 没有模式, 因为模式描述的是能力的形状而不是它的验证 状态.

官方SDK被隔离在下面 `src/modal/internal/`因为那个SDK 使用gRPC而不是HTTP 没有可注射的运输接缝;边界 是一个结构镜像,在构建时检查。 所有创造, 查询,执行,上传,删除操作都有明确的期限. 见 [modal 适配符注释](https://npmcn.com/package/%40agent-relay/sandbox/docs/modal.md) 依赖来源,提供者 限制、成本模型和能力证据.

## 发展

```bash
npm ci
npm run build      # tsc → dist/
npm run typecheck
npm test           # node:test
```

需要20号或更新的节点。 微软箱适配器本身的测试需要节点22+ 装入真正的 SDK; 没有它,它的 SDK 合同检查跳过而不是失败.

## 释放

仅通过手动发送 `Publish` 工作流程和默认为 一个干燥跑道。 推或合并时没有自动发布.

认证是 npm OIDC 信任的出版 —— 没有出版令牌到 存储。 真正的发布需要寄存器所有者注册此寄存器 和工作流程,作为 npmjs.org 软件包的可信任的发布者; 发布带 [来源](https://docs.npmjs.com/generating-provenance-statements) 证明 承诺和工作流程.

## 许可证

阿帕奇2.0 (英语). 见 [自由主义](https://npmcn.com/package/%40agent-relay/sandbox/LICENSE)。 。 。 .

## 常见问题

### @agent-relay/sandbox 是什么？

提供不可知的沙盒运行时间和代理工作量的管弦\.

### 如何安装 @agent-relay/sandbox？

在项目目录运行 npm install @agent-relay/sandbox，或使用 pnpm add / yarn add / bun add。

### @agent-relay/sandbox 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agent-relay/sandbox 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agent-relay/sandbox 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agent-relay/sandbox 可以商用吗？

@agent-relay/sandbox 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agent-relay/sandbox 的下载量有多少？

根据 npm 官方下载统计，@agent-relay/sandbox 在 2026/10/05 – 2026/11/03 这 30 天内被下载 3,802 次，日均约 127 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agent-relay/sandbox 还在维护吗？

最新版本 0\.1\.16 发布于 2026/09/16（1 个月前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/07/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。