Sandcastle
用一次 sandcastle.run() 在隔离沙箱中编排 AI 编码代理，并把分支提交合并回来。
- Star 数
- ★ 8.8k
- 最近更新
- 今天
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 54/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 需要同时启动多个 AFK 编码代理并行处理任务的工程团队
- 不适合
- 希望开箱即用、完全不想写 TypeScript 编排代码的团队
- 需要在无进程沙箱机制支持的老旧系统上直接运行的场景
- 期待图形界面而非代码与 CLI 的运营或非工程用户
- 源码审查
- 54/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Sandcastle 是一个 TypeScript 库，用于在隔离沙箱中编排 AI 编码代理。调用方只需执行一次 sandcastle.run()，库负责按可配置的分支策略把代理关进沙箱、运行代理，并将分支上产生的提交合并回主流程。它不绑定模型或代理厂商：内置使用操作系统自身进程沙箱的原生沙箱（Linux/WSL2 上的 Bubblewrap、macOS 上的 Seatbelt），也提供 Docker、Podman 等基于镜像的提供方，以及 Daytona、E2B、Fly.io Sprites、Modal、Vercel 等云端提供方，并允许自定义。文档按术语组织，涵盖核心概念、沙箱提供方、分支策略、代理提供方与会话、迭代与结构化输出、提示词、钩子、init、运行日志，以及 run()/createSandbox() 与 CLI 参考。典型用途是并行跑多个无人值守（AFK）代理、搭建评审流水线，或编排自有代理。
调用方在 TypeScript 代码中调用 sandcastle.run()，并配合 createSandbox() 创建或选择沙箱；Sandcastle 依据分支策略为每个代理准备独立分支，把代理进程隔离在沙箱中执行（原生沙箱走 Bubblewrap/Seatbelt，镜像提供方走 Docker/Podman，云端提供方走 Daytona、E2B、Fly.io Sprites、Modal、Vercel），并支持迭代执行、结构化输出、提示词、钩子与运行日志展示；代理在分支上产生的提交随后被合并回来。文档还提供 CLI 命令参考与 init 流程，方便在项目中初始化相关配置。
- 需要同时启动多个 AFK 编码代理并行处理任务的工程团队
- 想把代码评审变成流水线：代理在沙箱分支上改动，再由流程合并或审查
- 已在 Docker 或 Podman 环境中标准化、希望代理也用镜像沙箱隔离的团队
- 想借助 Daytona、E2B、Modal、Vercel 等云端提供方在远端运行代理的开发者
- 想用 TypeScript 把自家代理编排进现有 CI 或内部工具链的团队
如何安装或部署这个 Agent？
在项目目录中安装依赖并构建：
npm install
npm run build # Bundle with tsup
npm test # Run tests with vitest
npm run typecheck # Type-check源码未给出 npm 包名或发布版本的安装命令，README 仅记录了上述开发流程；使用前需自行确认包发布状态。原生沙箱依赖操作系统机制（Linux/WSL2 上的 Bubblewrap、macOS 上的 Seatbelt），镜像或云端提供方则需预先具备 Docker/Podman 或对应云账号与凭据。
如何使用这个 Agent？
核心用法是在自己的 TypeScript 代码中调用 sandcastle.run()，由 Sandcastle 负责沙箱与分支合并：
import { sandcastle } from "sandcastle";
await sandcastle.run({
// 具体参数见 docs/guide/run.md 与 docs/guide/core-concepts.md
});README 未给出 complete 的可运行参数示例，建议先按文档顺序阅读：docs/guide/getting-started.md（前置条件与快速开始）、core-concepts.md、sandbox-providers.md、branch-strategies.md、agent-providers.md。CLI 命令见 docs/guide/cli.md，初始化流程见 docs/guide/init.md；文档站点为 aihero.dev/sandcastle。
这个 Agent 有哪些优点和局限？
- 提供方无关：代理提供方与沙箱提供方均可替换，原生、镜像、云端三类路径并存
- 原生沙箱复用操作系统进程隔离（Bubblewrap/Seatbelt），无需额外容器运行时
- 把分支策略纳入编排：代理在独立分支上工作，提交可合并回来，便于并行与评审
- 覆盖迭代、结构化输出、提示词、钩子、运行日志等执行环节，接口面较完整
- 采用 MIT 许可，文档按术语逐页组织并配有术语表
- 以 TypeScript 库为主要入口，采用者需要编写编排代码，而非开箱即用的产品
- 部分沙箱提供方（Daytona、E2B、Fly.io Sprites、Modal、Vercel）依赖第三方云账号与凭据
- 原生沙箱按平台不同（Bubblewrap/Seatbelt），跨平台行为存在差异
- README 未给出包名安装命令与可直接运行的最小示例，上手需依赖 docs/guide 阅读
- 仓库未标注 GitHub topics，生态与社区信号需要自行评估
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Sandcastle 当前 | 54 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 8.8k | 今天 | TypeScript | — |
| Warren | 76 · 表现良好 | 自托管服务免费 + 模型费 | ★ 513 | 19 天前 | TypeScript | Claude Code |
| Omnigent | 62 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 11k | 今天 | Python | ChatGPT · Codex · Claude Code · Claude.ai · OpenAI API · Claude API |
| Best of Agent Harnesses | 75 · 表现良好 | MCP 服务器免费 + 模型费 | ★ 1.4k | 1 天前 | Python | Claude Code · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
least_privilege：原生 bwrap/seatbelt 提供私有 home、只读系统目录、隐藏凭据，且明确不静默回退到 noSandbox()，但网络完全开放（含 host localhost），故扣分至 2。user_confirmation：noSandbox() 在 run() 中无运行时确认，ADR-0015 明确由调用方承担风险，仅靠 import 作为 opt-in，扣至 1。data_flow_transparency：文档清楚说明 env、登录、git 身份、session 复制路径，但 .sandcastle/.env 中的密钥会被转发进沙箱（E2B 章节明示），存在敏感数据外流面，扣至 2。sensitive_data_handling：私有 home 与 env 白名单较好，但 seatbelt 不保证隔离 Keychain、.env 密钥转发进沙箱，扣至 2。dependency_security：package.json 大量 peer/dev 依赖使用 ^ 范围，无锁文件或审计证据，扣至 1。external_effects：run() 会合并提交回分支、云端 provider 创建/删除远端资源，缺少默认 dry-run 或确认，扣至 1。rollback：ADR-0017 显示 syncOut 曾因 base 错误导致整轮提交丢失，修复依赖 ref 机制，但无通用回滚/撤销 API，扣至 1。source_attribution：MIT 与作者署名存在，但发布者身份未经验证、包名 @ai-hero/sandcastle 与仓库 mattpocock/sandcastle 不一致，扣至 1。
self_consistency：README、sandbox-providers.md、ADR 与 package.json exports 基本一致（provider 列表、导入路径吻合），但 README 提及 Daytona 而 provider 表未列，存在轻微不一致，扣至 2。dependency_availability：云端 provider 依赖可选 peer 依赖（e2b、modal、@fly/sprites、@vercel/sandbox、@daytona/sdk），需用户自行安装且版本范围宽，扣至 1。failure_messages：文档展示 NativeSandboxUnavailableError 带 fixCommand、idle 超时错误、sudo 拒绝错误，测试也断言错误信息，表现较好，给 2。
audience_and_scenarios：覆盖并行 AFK agent、review 流水线、多 provider 场景，受众明确，给 2。capability_boundaries：文档对每个 provider 的隔离强度、限制（无 PID namespace、setsid 逃逸、无 root、无 interactive）描述非常详尽，给 3。trigger_precision：run() 触发依赖 agent 完成信号与 idle 超时，但无显式触发条件/幂等说明，扣至 1。environment_fit：支持 Linux/WSL2/macOS/Windows(WSL2) 与多种云 provider，但 macOS 需 14+、Ubuntu 24.04 需 AppArmor 配置，扣至 2。
information_architecture：docs/guide 一页一术语并有 glossary，结构清晰，给 2。install_notes：README 有 npm install/build/test，各 provider 有安装说明，给 2。naming_stability：包名 @ai-hero/sandcastle 与仓库名 sandcastle 不一致，且 ADR 显示 AnySandboxProvider 弃用、interactive() 将在 v1 移除，API 处于变动期，扣至 1。examples_and_faq：文档含大量代码示例与自定义 provider 示例，但无独立 FAQ，给 2。known_limitations：Containment 章节与 ADR 详尽列出限制，给 3。license：MIT LICENSE 文件完整，给 3。versioning_changelog：使用 changesets 但仓库内无 CHANGELOG 文件，版本 0.13.0 为 pre-1.0，扣至 1。maintenance_responsibility：无 SECURITY.md、无维护者承诺、发布者未验证，扣至 1。
output_usability：run() 返回 completionSignal、commits、iterations、sessionFilePath，输出结构化可用，给 2。marginal_value：在已有 agent CLI 之上提供沙箱编排与分支合并，有明确增量价值，但同类工具存在，给 2。cost_benefit：云端 provider 有超时/计费风险（E2B 1 小时上限、Modal 默认 1 小时），文档未量化成本，扣至 1。
claim_traceability：README 声称的 provider 与文档、package.json exports 可对应，但部分声明（如 Daytona）无对应文档页，扣至 1。cross_source_corroboration：README、guide、ADR、测试之间部分互相印证（bwrap 行为有测试），但无独立第三方验证，扣至 1。fact_inference_separation：文档多为设计陈述，ADR 区分决策与后果较好，但研究文档 permissions-systemic-fix.md 混入推测（'in order of likelihood'），扣至 1。
- noSandbox() 可在 run() 中直接以主机权限运行 agent，无运行时确认，调用方需自行承担风险。
- 原生沙箱网络完全开放，可访问 host localhost 上的服务；seatbelt 不保证隔离 macOS Keychain，且 setsid 进程可逃逸进程组。
- 云端 provider 依赖可选 peer 依赖且版本范围宽，需自行安装并核对版本；仓库内无锁文件或依赖审计证据。
- 包名 @ai-hero/sandcastle 与仓库 mattpocock/sandcastle 不一致，发布者身份未经验证，安装前应核对来源。
- run() 会合并提交回分支并创建/删除云端资源，缺少默认 dry-run 或回滚 API；ADR-0017 记录过整轮提交丢失的历史缺陷。
- 版本 0.13.0 为 pre-1.0，API 处于变动期（AnySandboxProvider 弃用、interactive() 计划移除），升级需谨慎。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
Minor Changes - d99fff8: Add an E2B isolated sandbox provider, e2b() from @ai-hero/sandcastle/sandboxes/e2b. It needs the optional e2b peer dependency and E2B_API_KEY (or the apiKey option). Use a template that ships your agent's CLI, such as e2b({ template: "claude" }). - 8783573: Add modal(), an isolated sandbox provider for [Modal](https://modal.com) sandboxes, at @ai-hero/sandcastle/sandboxes/modal. Install modal (an optional peer dependency) and set MODAL_TOKEN_ID and MODAL_TOKEN_SECRET, or pass tokenId and tokenSecret. By default it builds a `node:24-bookwo …在 GitHub 查看 ↗ -
发布说明摘录
Highlights - Native sandboxes. bwrap() (Linux and WSL2) and seatbelt() (macOS) run the agent in an OS sandbox with no container and no image. They are now the documented default. sandcastle init --sandbox bwrap scaffolds a project that needs no Dockerfile. - Resume for more agents. Copilot, Cursor and OpenCode sessions can now be resumed; OpenCode can also fork. - sandboxId on the sandbox handle (the container name on Docker and Podman, the sandbox's name or id on Vercel and Daytona), and capDrop for Docker and Podman. …在 GitHub 查看 ↗ -
发布说明摘录
Minor Changes - 1e15922: Bump default Claude Code model from claude-opus-4-7 to claude-opus-4-8. The new default applies to the DEFAULT_MODEL constant, the claude-code agent entry surfaced by sandcastle init, and the scaffolded templates (blank, parallel-planner, parallel-planner-with-review). Passing an explicit model to claudeCode(...) is unaffected. …在 GitHub 查看 ↗