Sandbox SDK

一套 TypeScript API 在 11 个云 provider 或本地 Docker 中运行命令、编辑文件与提供预览。

Star 数
★ 117
最近更新
1 天前
License
MIT
主语言
TypeScript

30 秒速览

运行形态
代码库 / SDK
可在哪里用
通用 · 跨平台
费用
软件免费,模型调用费用自付
上手难度
低 · 几分钟可跑通
开始前需要
Node.js 22+ 或 Bun 1.3+各 provider 的 SDK(可选 peer,例如 e2b)Docker(仅本地 provider 需要)Shell / 命令行网络访问本地文件系统
典型场景
需要给 AI 编码 agent 提供隔离执行环境的团队:用 sandboxTools 与 AI SDK 组合,让模型跑测试并修复失败。
不适合
  • 想要开箱即用 GUI 或托管服务的团队
  • 必须完全离线、不能装任何 provider SDK 的环境
  • 只用 Python 或非 TypeScript 后端的项目
官网
sandbox-sdk.app ↗ 来自 GitHub 仓库设置
维护状态
近 30 天有提交最近提交 2026-11-20最新版本 @opencoredev/[email protected](2026-11-20)近 7 天每天 +0.6 ★

这个 Agent 能做什么,适合哪些场景?

Sandbox SDK 是 OpenCore 开源的 MIT 许可 TypeScript 库,把创建沙箱、执行命令、读写文件、启动开发服务器、生成端口预览链接、Git 克隆/提交/推送、暂停与快照等能力收敛到单一 createSandbox() 接口上。核心包是 @opencoredev/sandbox-sdk,每个执行后端以独立子路径导出(/e2b、/daytona、/vercel、/upstash、/railway、/tenki、/freestyle、/local 等),切换 provider 只需改一行 import,各 provider 官方 SDK 作为可选 peer 依赖按需安装。它还提供 memory() 内存假沙箱,无需账号即可试用与测试,另有 runConformance 用于校验自实现的 Provider。sandboxTools 可把沙箱包装成 AI SDK、Mastra、OpenAI Agents SDK 可调用的工具集,注册的密钥不会进入模型上下文。运行边界在你自己的服务端代码中:沙箱由 provider 创建,预览端口由 provider 规则决定。

调用 createSandbox(provider, { key }) 按 provider 创建或复用沙箱,await using 在作用域结束时按有无 key 决定销毁或仅调用 close()。通过 box.run("npm test") 或 `box.$git checkout ${branch} 执行命令、流式读取输出并设置超时,非零退出码返回 ok: false 而不是抛错;box.files.write()/read()/edit()/search()/upload() 操作文件;box.start("npm run dev", { ready: { port: 3000 } }) 启动服务并等待端口可用,box.preview(3000) 取回访问 URL;box.git.clone()/commit()/push() 在不泄露 token 的前提下操作仓库;box.pause()/resume()/snapshot() 在支持该能力的 provider 上暂停、恢复与快照,TypeScript 类型会标明哪些 provider 支持。失败统一为带 code 的 SandboxError。sandboxTools(box, { root }) 将同一沙箱暴露为 run、read_file、write_file、edit_file` 及后台进程控制等工具交给模型调用。

  1. 需要给 AI 编码 agent 提供隔离执行环境的团队:用 sandboxTools 与 AI SDK 组合,让模型跑测试并修复失败。
  2. 已在 E2B 上运行但担心供应商锁定的项目:保留同一份业务代码,逐 provider 迁移或做多后端 A/B 对比。
  3. 后端服务需要为用户生成预览链接(如在线 IDE、低代码平台):用 box.start + box.preview 起 dev server 并取回 URL。
  4. CI 或集成测试需要真实 Linux 环境的场景:先用 memory() 跑通 API,再切到 E2B 或本地 Docker 验证。
  5. 希望自建沙箱基础设施的团队:用 /local provider 在本机 Docker 中执行,无需云账号。
  6. 需要对多家沙箱厂商做性能与能力评估的工程团队:仓库自带 bench 基准工具与 runConformance 一致性测试。
  7. 需要在代码里做多轮 Git 操作又不想暴露 token 的场景:用 box.git.clone()/commit()/push() 封装凭据。

安装与配置要点

摘自下方的安装和使用说明,以项目 README 的最新说明为准。

安装 / 启动命令
  • npm install @opencoredev/sandbox-sdk
  • npm install e2b
  • npm install ai zod e2b
环境变量
E2B_API_KEY AI_GATEWAY_API_KEY
运行环境
Node.js 22+ · Bun 1.3+
安装说明涉及
Linux · Docker

如何安装或部署这个 Agent?

安装运行时要求 Node.js 22+ 或 Bun 1.3+。主包与所需 provider 的官方 SDK 分开安装,用哪个装哪个。

npm install @opencoredev/sandbox-sdk
npm install e2b

如果只想先跑通 API,不需要任何账号或 Docker,memory() provider 无需额外依赖。本地容器执行则安装后确保 Docker 已运行,并只装主包:

npm install @opencoredev/sandbox-sdk

如何使用这个 Agent?

先用内存假沙箱验证 API,无需任何密钥:

import { createSandbox } from "@opencoredev/sandbox-sdk";
import { memory } from "@opencoredev/sandbox-sdk/memory";

await using box = await createSandbox(memory());

await box.files.write("hello.txt", "hello from the sandbox\n");
const result = await box.run("cat hello.txt");
console.log(result.ok, result.stdout); // true "hello from the sandbox\n"

改用真实 Linux 机器时只换 provider;E2B 从环境变量读取 E2B_API_KEY:

import { createSandbox } from "@opencoredev/sandbox-sdk";
import { e2b } from "@opencoredev/sandbox-sdk/e2b";

// Reads E2B_API_KEY from the environment. Run `npm install e2b` first.
await using box = await createSandbox(e2b());

await box.files.write("hello.py", "print('hello from the sandbox')");
const result = await box.run("python3 hello.py");
console.log(result.stdout); // "hello from the sandbox\n"

把它交给 agent 时,额外安装 AI SDK、zod 和 provider 包,并在服务端设置 AI_GATEWAY_API_KEY 与 E2B_API_KEY:

npm install ai zod e2b
import { generateText, stepCountIs } from "ai";
import { createSandbox } from "@opencoredev/sandbox-sdk";
import { sandboxTools } from "@opencoredev/sandbox-sdk/ai";
import { e2b } from "@opencoredev/sandbox-sdk/e2b";

await using box = await createSandbox(e2b());
await box.git.clone("https://github.com/opencoredev/sandbox-sdk", { dir: "app", depth: 1 });

const { text } = await generateText({
  model: "anthropic/claude-opus-5-5",
  tools: sandboxTools(box, { root: "/workspace/app" }),
  stopWhen: stepCountIs(20),
  prompt: "Run the tests and fix the first failure.",
});

要在下一次请求里找回同一个沙箱,创建时传入 key:

await using box = await createSandbox(e2b(), { key: "user:123" });

需要自定义后端时,实现 @opencoredev/sandbox-sdk/provider 导出的 Provider 接口,再用 @opencoredev/sandbox-sdk/testing 的 runConformance 做一致性测试。从 0.2 升级到 1.0 属于破坏性变更,需按官方 upgrade-from-0-2 文档逐项调整。

这个 Agent 有哪些优点和局限?

优点
  • 统一接口覆盖 11 个云 provider 加本地 Docker,切换后端只改一行 import,显著降低沙箱厂商锁定风险。
  • memory() 内存沙箱让开发与测试无需账号、密钥或 Docker,第一次跑通 API 成本极低。
  • await using 与带 code 的 SandboxError 把生命周期清理和错误分支做成语言级约定,非零退出码返回 ok: false 而非抛异常。
  • sandboxTools 直接对接 AI SDK、Mastra、OpenAI Agents SDK,并保证注册的密钥不会进入模型上下文。
  • 自带 runConformance 一致性测试与 bench 基准工具,便于自建 provider 或横向选型对比。
  • 各 provider 官方 SDK 为可选 peer 依赖,按需安装,不强迫引入全部依赖。
局限
  • 从 0.2 到 1.0 是破坏性 API 变更,已有代码必须按迁移指南改写。
  • 暂停、恢复与快照等能力依赖具体 provider,跨后端能力并不完全对等。
  • 每个真实 provider 都需要安装其官方 SDK 并配置对应凭据,多后端场景下依赖与密钥管理成本上升。
  • 仅支持服务端 TypeScript,运行时要求 Node.js 22+ 或 Bun 1.3+,其他语言后端无法直接使用。
  • 预览链接规则、凭据方式与能力上限由各 provider 决定,需要逐个查阅 provider 文档。

这个 Agent 与同类方案有什么区别?

README 直接把 E2B、Daytona、Vercel Sandbox、Upstash Box、Railway、Tenki、Freestyle、Docker 等列为可替换的后端,并提到 E2B 自托管(E2B Embed)与 Docker 之间的取舍文章;它定位为这些厂商 SDK 之上的统一抽象层,而非替代某一个沙箱产品。

与相关度最高的同类 agent 并排比较关键指标。

Agent 源码审查 形态 / 费用 Star 最近更新 主语言 完整支持的平台
Sandbox SDK 当前 63 · 存在缺口 代码库 / SDK免费 + 模型费 ★ 117 1 天前 TypeScript —
Judge0 在线代码执行系统 52 · 缺口较多 自托管服务免费版 + 付费版 ★ 4.5k 26 天前 HTML —
Capsule 沙箱运行时 54 · 缺口较多 命令行工具免费 ★ 304 1 个月前 Rust —
AI SDK 54 · 缺口较多 代码库 / SDK免费 + 模型费 ★ 28k 今天 TypeScript OpenAI API · Claude API

FollowAgents 如何评估这个 Agent?

FollowAgents 源码审查 · FARS-2.1
存在缺口
63/ 100 五分制 3.2 / 5
本评测基于 2026年11月11日 的源码;此后该项目发布了 2 个正式版本,尚未复审。分数与结论只代表评测时的版本。 最近版本 ↓
信任安全 16/29
可靠稳定 9/14
适用触发 14/18
规范维护 11/18
有效结果 9/13
证据核验 4/8
查看各维度的扣分理由
信任安全16 / 29 · 2.8/5

least_privilege:createSandbox 对 size/network/snapshot 能力做前置校验,SECURITY.md 说明 Local 默认拒绝出网与宿主绑定,属较扎实的权限收敛(2)。user_confirmation:无任何面向用户的确认流程,仅 bench 有 --yes 预算确认,产品层缺失(1)。data_flow_transparency:SECURITY.md 明确不添加遥测、不得记录命令/文件/密钥,Redactor 与 preview token 处理有说明(2)。sensitive_data_handling:secrets 经 Redactor 注入、preview 头被剥离、错误 cause 提示勿记录,但未见密钥轮换或日志审计实现(2)。dependency_security:CI 固定 action SHA、frozen-lockfile,但根 package.json 依赖用 ^ 范围且未见依赖审计/SCA 流程(1)。external_effects:创建/销毁/中止路径有显式 destroy 与幂等 stop,但真实云资源副作用依赖 provider(2)。rollback:abort 后销毁迟到沙箱、stop 幂等、withSandbox 保留原错误,回滚语义清晰(2)。source_attribution:MIT 与 OpenCore 署名清楚,但发布者身份未经验证,且 README 与 SKILL.md 对 provider 列表/API 形态描述不一致,削弱可追溯性(1)。

可靠稳定9 / 14 · 3.2/5

self_consistency:README 用 createSandbox(e2b()) 与 createSandbox(memory()),SKILL.md 却用 createSandbox({ provider: local() }),且 provider 列表(Ascii Box、Superserve、Boat 等)与 README 表格不一致,属实质矛盾(1)。dependency_availability:provider SDK 为可选 peer 并逐项列出安装包,Node 22+/Bun 1.3+ 有说明,但根 engines 写 >=24 与 README 的 22+ 冲突(2)。failure_messages:SandboxError 带 code,validate 中错误信息具体且可操作(如“Creation refused. Provider cannot enforce size.”),表现突出(3)。

适用触发14 / 18 · 3.9/5

audience_and_scenarios:面向服务端 TypeScript 开发者与 agent 集成,覆盖多 provider、Docker、memory 测试场景(2)。capability_boundaries:capabilities 集合、hasCapability 类型收窄、requireCapability 与 validate 拒绝不支持操作,边界表达非常明确(3)。trigger_precision:SKILL.md 的 description 触发条件较清楚,但文档需外部抓取 llms.txt,静态包内触发信息有限(2)。environment_fit:Node/Bun、Docker、多云端适配良好,但 Node 版本声明冲突与 beta 的 AgentOS 依赖带来适配不确定性(2)。

规范维护11 / 18 · 3.1/5

information_architecture:README 有安装、快速开始、能力表、provider 表、仓库结构,结构清晰;但 AGENTS.md 指向的 1.0 重写分支与文档站点并存,信息层级略乱(2)。install_notes:npm 安装、peer 依赖、Node/Bun 版本均有说明,但版本要求自相矛盾(2)。naming_stability:README 提示 1.0 破坏性变更,SKILL.md 与 README 的 API 形态不一致,命名稳定性存疑(1)。examples_and_faq:有 quickstart、agent 工具示例、examples 目录与博客指南,但无正式 FAQ(2)。known_limitations:EARLY_ACCESS.md 被引用、SECURITY.md 明确列出不覆盖范围、provider 文档说明限制(2)。license:MIT 全文完整,版权方明确(3)。versioning_changelog:有 CHANGELOG 链接、changeset 流程与 CI 强制 changeset,但包内未见实际 changelog 内容(2)。maintenance_responsibility:有 SECURITY.md 联系邮箱、RELEASING.md 与 issue 渠道,但发布者未经验证、维护者身份不明(1)。

有效结果9 / 13 · 3.5/5

output_usability:API 返回结构化 RunResult(ok/stdout)、SandboxError 带 code,输出可直接消费(2)。marginal_value:统一多 provider 的抽象确有价值,但同类沙箱抽象已存在,差异化有限(2)。cost_benefit:可选 peer 依赖、memory 假沙箱便于测试、bundle 体积检查,成本控制有考虑;但多 provider 适配维护成本高(2)。

证据核验4 / 8 · 2.5/5

claim_traceability:README 声称 11 个 provider 与“同一代码切换”,但 SKILL.md 列表不同,且部分 provider 无文档链接,声明难以逐条追溯(1)。cross_source_corroboration:README、SKILL.md、docs/providers/sandboxer.md 与源码在 provider 集合和 API 签名上互相矛盾,交叉印证不足(1)。fact_inference_separation:SECURITY.md 明确区分“SDK 不提供隔离”与 provider 边界,文档对能力与限制的表述较克制(2)。

风险与缓解建议
  • README 与 SKILL.md 对 createSandbox 的调用形态和 provider 列表不一致,集成前应以源码与 docs/spec.md 为准,勿直接照抄示例。
  • 根 package.json 的 engines 要求 Node >=24,而 README 写 Node 22+,部署环境需自行核实。
  • SECURITY.md 明确 SDK 不提供执行隔离,安全边界完全依赖所选 provider;Local 依赖 beta 的 AgentOS,不宜用于不可信负载。
  • 发布者身份未经验证,且 AGENTS.md 指向一个 1.0 重写分支,当前 API 可能处于不稳定状态。
  • 本评估为静态源码审阅,未执行任何代码或测试,bench 与 CI 的实际通过情况未知。
证据充分度:低 评估于 2026年11月11日 审查版本 c0be02db3068 评估后仓库已有新提交,评分可能未覆盖最新改动
查看完整评分方法 →
你是这个项目的维护者?把 FARS 徽章加到 README

徽章显示当前的评审分数和结论,点击回到本页。重新评审后约一小时内更新。

FARS

[![FARS 评测](https://followagents.com/badge/sandbox-sdk.svg?lang=zh)](https://followagents.com/zh/agents/sandbox-sdk)
<a href="https://followagents.com/zh/agents/sandbox-sdk"><img src="https://followagents.com/badge/sandbox-sdk.svg?lang=zh" alt="FARS 评测"></a>

最近版本

来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。

  1. 发布说明摘录
    Minor Changes - 9b43183: Add the Beam provider, beam() from @opencoredev/sandbox-sdk/beam. It runs Beam Sandboxes through Beam's official @beamcloud/beam-js SDK (1.1.6 or later), an optional peer. It supports commands, files (files over Beam's gateway limits move in pieces), listing and reconnect, public preview URLs, memory snapshots and restore, and size presets (small 1 vCPU / 2048 MiB, medium 2 / 4096, large 4 / 8192) and exact sizes in whole vCPUs and MiB. With no size, a sandbox gets Beam's own default of 1 vCPU and 128 MiB. Keys are best-effort, stored in a marker file in …
    在 GitHub 查看 ↗
  2. 发布说明摘录
    Minor Changes - 62bd329: Add the Baseten provider, baseten() from @opencoredev/sandbox-sdk/baseten. It runs Baseten Sandboxes through Baseten's official @basetenlabs/sandbox SDK (0.5.0), an optional peer. Keys are exact (unique sandbox names). It supports size presets and the exact sizes 1 vCPU / 2048 MiB, 2 / 4096 and 4 / 8192 (Baseten sets CPU from memory), timeoutMs and idleTimeoutMs as Baseten lifecycle policies, public preview URLs without declared ports, and a volume option that creates, mounts and deletes a volume per sandbox, for workspaces too large to keep in memor …
    在 GitHub 查看 ↗
  3. 发布说明摘录
    Patch Changes - 83ff7b9: Commands add less overhead on top of each provider's own SDK. Freestyle and Superserve keep one guest supervisor per sandbox instead of starting Python for every command. boxd, Freestyle, Superserve and Tenki supervisors start faster. E2B and Upstash no longer wrap each command in an activity script; reapSandboxes({ idleOnly: true }) finds running commands by scanning for the SANDBOX_SDK_RUN=1 tag instead, and still treats a sandbox it can't inspect as busy. On E2B and Upstash, files.edit takes one call and changes the file the way that provider's own write …
    在 GitHub 查看 ↗

常见问题

使用这个 SDK 本身要付费吗?
SDK 采用 MIT 许可,可免费使用。但除 memory() 和本地 Docker 外,每个云 provider 都需要其自身账号与密钥,费用按该 provider 的计费规则结算。
不用任何云账号能试用吗?
可以。memory() 是进程内的假沙箱,无需账号与 Docker,适合试 API 和写测试;要真实 Linux 环境再切换到 E2B 或本地 Docker。
切换沙箱厂商需要改多少代码?
README 说明只需更换 provider 的 import。但暂停、恢复、快照等能力只在部分 provider 上存在,TypeScript 类型会标明支持范围,跨后端时需评估这些能力差异。
沙箱什么时候会被销毁?
不带 key 创建的沙箱在 await using 作用域结束时被删除,即使代码抛错;带 key 时仅调用 close() 保留运行,需自行调用 destroy()。
能接入自己的沙箱后端吗?
可以。实现 @opencoredev/sandbox-sdk/provider 导出的 Provider 接口,并用 @opencoredev/sandbox-sdk/testing 的 runConformance 验证一致性。
Sandbox SDK 官网是什么?
Sandbox SDK 的 GitHub 仓库填写的官网是 https://sandbox-sdk.app。这个链接由仓库作者设置;源码在 GitHub(opencoredev/sandbox-sdk)。
Sandbox SDK 开源吗?
开源。源码在 GitHub(opencoredev/sandbox-sdk),许可证是 MIT。
Sandbox SDK 还在维护吗?
在维护。GitHub 上最近一次提交是 2026-11-20,在最近 30 天内。最新版本是 @opencoredev/[email protected](2026-11-20)。
Sandbox SDK 是谁开发的?
Sandbox SDK 由 GitHub 账号 opencoredev 发布。FollowAgents 没有核实这个账号背后是哪个人或公司。
这页内容对你有帮助吗?
在 GitHub 查看 ↗ 安装 ↓

对比同类 Agent

用同一套 FARS 评审,横向比较这个 Agent 所属的短名单。

相关核心概念