用 Sandcastle 把编码 Agent 关进原生沙箱：bwrap/seatbelt 选型、init 配置与 sandcastle.run() 实操

# 官方包名是 @ai-hero/sandcastle，不是 sandcastle
npm install --save-dev @ai-hero/sandcastle

# 运行入口脚本需要 tsx（init 生成的是 .mts / .ts）
npm install --save-dev tsx

# 确认 Git 可用，Sandcastle 依赖 worktree 与提交合并
git --version

npx @ai-hero/sandcastle init

# 复制模板
cp .sandcastle/.env.example .sandcastle/.env

# 在宿主机上生成 Claude Code 的 OAuth token
claude setup-token

# 编辑 .sandcastle/.env，填入下列之一（按模板注释取消对应行）
CLAUDE_CODE_OAUTH_TOKEN=你的_token
# ANTHROPIC_API_KEY=你的_key

# 需要 gh 操作时，也在这里放 GH_TOKEN
GH_TOKEN=你的_github_token

# 务必把 .env 排除出版本库
echo ".sandcastle/.env" >> .gitignore

import { run, claudeCode } from "@ai-hero/sandcastle";
import { bwrap } from "@ai-hero/sandcastle/sandboxes/bwrap";
import { seatbelt } from "@ai-hero/sandcastle/sandboxes/seatbelt";

// 按系统挑原生沙箱：macOS 用 Seatbelt，其余用 Bubblewrap
const sandbox = process.platform === "darwin" ? seatbelt() : bwrap();

await run({
  agent: claudeCode("claude-opus-4-8"),
  sandbox,
  promptFile: ".sandcastle/prompt.md",
});

# .sandcastle/prompt.md 里写清楚、可验收的一件小事
把 README.md 里的安装说明补上一行 Node 版本要求，
只改 README.md，不要动其他文件。

# 执行
npx tsx .sandcastle/main.mts

文件系统：Agent 只能写仓库（或其 worktree）、Sandcastle 挂载的 git 目录、
          私有 temp 与私有 home；家目录、SSH key、其他仓库不可见。
工具链：  宿主 PATH 上的目录可读，nvm 装的 codex / ~/.local/bin 下的 claude 可用；
          等于家目录或其祖先的 PATH 项、含 .git 的安装根目录不会被挂载。
环境变量：Agent 只看得到 Sandcastle 传入的变量，外加 PATH / HOME / TMPDIR。
进程：    Agent 不能给宿主进程发信号；沙箱关闭时其派生的进程一并被清理。
网络：    开放，包含宿主的 127.0.0.1（这是风险，不是便利）。
权限：    无 root；exec 与钩子的 sudo: true 会被拒绝并提示改用 docker()。

import { NativeSandboxUnavailableError } from "@ai-hero/sandcastle";

try {
  bwrap();
} catch (error) {
  if (error instanceof NativeSandboxUnavailableError) {
    console.error(error.message);    // 人话解释为什么不可用
    console.error(error.fixCommand); // 例如 "sudo apt install bubblewrap"
  }
}

# E2B：Node 22.19+，key 放 shell，不要放 .sandcastle/.env
npm install e2b
export E2B_API_KEY=你的_key

# Modal：Node 22+，或让 SDK 读 ~/.modal.toml
npm install modal
export MODAL_TOKEN_ID=你的_id
export MODAL_TOKEN_SECRET=你的_secret

# Fly.io Sprites：SDK 要求宿主 Node 24+
npm install @fly/sprites
export SPRITES_TOKEN=你的_token

import { run, claudeCode } from "@ai-hero/sandcastle";
import { e2b } from "@ai-hero/sandcastle/sandboxes/e2b";

await run({
  agent: claudeCode("claude-opus-4-8"),
  sandbox: e2b({ template: "claude" }), // 官方预置模板才带 agent CLI
  prompt: "Fix issue #42 in this repo.",
});