@ agent-relay/ sandbox (英语)

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

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

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

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

安装

npm install @agent-relay/sandbox

运行您的第一个工作量

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

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}死吗? 供应商收费和限额仍然适用.

从一个沙盒到软件厂

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

托管的AgentWorkforce集成公司可自主核算 那个工厂 SDK仍然可用于自己的供应商账户,并且确实 不需要Workforce代理登录。 见 建立融合合同 对于边界,一个主机“与代理Workforce连接”的经验可以执行.

提供者账户设置

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

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

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

提供者适配器

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

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

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的要求,它们并非全部 与本套件相同:

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

微沙盒能力对后端敏感

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

两种值都描述此软件包的特性 已设立没有什么 提供者文档. '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 (前为: 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/; 公开 配置和能力元数据不导入供应商类型。 所有创造, 查询、执行、生命周期和删除操作都有明确的期限。 见 自由式适配符注释 供养来源, 供应商的制约和能力证据.

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 适配符注释 供养来源, 能力证据,以及活性-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 适配符注释 依赖来源,提供者 限制、成本模型和能力证据.

发展

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

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

释放

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

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

许可证

阿帕奇2.0 (英语). 见 自由主义。 。 。 .