sandbox-runtime 怎么安装：srt 验证与沙箱配置

拾光·开源拾遗内容创作者 2026-11-04 128 阅读

sandbox-runtime（命令行简称 srt）用于在操作系统层限制进程的文件、网络和 Unix socket 访问，适合给 AI Agent、MCP 服务或本地命令加一层隔离。

截至 2026-11-01，Anthropic 官方仓库仍把 Sandbox Runtime 标为 Beta Research Preview。现在值得配置，是因为它已经能通过 npm 安装并直接用 srt 启动受限进程；但研究预览阶段的 API 和配置格式仍可能变化，不宜直接用于没有回滚方案的生产任务。

安装前先确认平台与命令环境

官方实现使用 macOS 的 sandbox-exec 和 Linux 的 bubblewrap，网络访问则由代理过滤。以下三项要在安装前完成。

确认系统：三平台都受官方支持——macOS 用 sandbox-exec（Seatbelt profiles）、Linux 用 bubblewrap（容器化+网络命名空间隔离）、Windows 用专用 srt-sandbox 本地用户账号（基于该 SID 的 Windows Filtering Platform 出站栅栏 + 写受限令牌 + 工作树显式 ACE）。此前“机制只对应 macOS 和 Linux”的说法与官方 README 矛盾，已更正。各平台安装命令不同：不要在 Windows 上照抄下面的 Linux/macOS 命令；另可到仓库 Releases/Changelog 核对当前版本（changelog 显示已到 v0.0.76，以页面当下为准）。
确认 Node.js 与 npm 已可用，分别执行：

node -v
npm -v

两条命令都应返回版本号；如果终端提示找不到命令，应先安装或启用 Node.js，而不是反复执行 npm 安装。

确认网络与代理：执行 curl anthropic.com 应能正常返回页面。该测试用于区分“目标网站不可达”和“沙箱主动拦截”。如果安装前已经无法访问，应先处理本机网络。

官方给出的安装命令没有登录 Anthropic 账号、订阅或付款步骤，因此安装本身不要求账号权限，也没有额外费用。

三种安装方式怎么选

当前官方仓库给出的安装命令是 npm 全局安装。检索资料中还存在 Homebrew 安装、源码构建以及同名的 Python/Rust 包，不能把它们混为同一个项目。

方式	完整命令或入口	适合谁	主要风险
官方 npm 包	`npm install -g @anthropic-ai/sandbox-runtime`	大多数 macOS、Linux 用户	全局安装会修改 npm 的全局包目录
Homebrew 安装	`brew install anthropic-experimental/tap/srt`	已使用 Homebrew、希望由包管理器升级的人	资料中的 tap 属于 `anthropic-experimental`，与当前官方仓库组织名不同，安装前应确认 tap 来源
源码构建	`git clone https://github.com/anthropics-experimental/sandbox-runtime.git`<br>`cd sandbox-runtime && cargo build --release`	需要审查源码、固定分支或修改实现的人	需要 Rust 工具链，并承担自行升级与编译成本
容器隔离	项目目标本身是“无需容器”，不作为官方安装步骤	已经采用 Docker 等隔离机制的人	多一层系统隔离，配置和排错复杂度更高

优先选择 npm 方案：命令最短，而且直接对应官方仓库的 Installation。Homebrew 与源码命令来自 LearnAgent 的 Agent 沙箱实战，适合作为补充路径，不应覆盖官方仓库当前提供的安装入口。

还要注意同名包：PyPI 上的 sandbox-runtime 是另一个 Python 项目，Linux 依赖、配置字段和运行机制都不同。不要因为包名相同就执行它的 pip 或 uv 命令来替代 srt。

用官方命令安装并验证

确认 Node.js 和 npm 可用后，执行官方安装命令：

npm install -g @anthropic-ai/sandbox-runtime

安装结束后，先运行一个允许访问当前目录的读取测试：

srt " cat README.md "

如果测试文件存在，输出中应出现 Running: cat README.md，随后显示文件内容；仓库 README 给出的现象是当前目录访问被允许。

再测试一个明确禁止读取的敏感文件路径：

srt " cat ~/.ssh/id_rsa "

预期输出包含：

cat: /Users/ollie/.ssh/id_rsa: Operation not permitted

路径会随当前用户名变化。真正需要确认的是程序显示 Operation not permitted，而不是照抄示例里的用户名。如果 srt 提示找不到命令，应重新打开终端让 shell 刷新 PATH；若仍失败，可执行 npm prefix -g 查看 npm 全局目录，再检查该目录是否位于当前 PATH 中。

用 `srt` 包装 MCP 服务

srt 不只用于一条 Bash 命令，也能作为 MCP 服务的启动器。MCP（Model Context Protocol，模型与外部工具通信的协议）配置文件通常位于项目中的 .mcp.json。

未经沙箱限制时，配置直接启动文件系统 MCP 服务：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

改为由 srt 启动后，写入：

{
  "mcpServers": {
    "filesystem": {
      "command": "srt",
      "args": ["npx", "-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

然后在 ~/.srt-settings.json 中配置文件权限：

{
  "filesystem": {
    "denyRead": [],
    "allowWrite": ["."],
    "denyWrite": ["~/sensitive-folder"]
  }
}

这套配置把允许写入的位置限定为当前目录，同时明确排除敏感目录。它表达的是“默认限制、显式放行”的思路：新增目录时，应修改 allowWrite，而不是把整个用户目录加入白名单。

两个常见拦截结果怎么处理

`Connection blocked by network allowlist`

官方示例中，srt " curl anthropic.com " 请求成功，而 srt " curl example.com " 会输出：

Connection blocked by network allowlist

这说明网络代理已按允许列表拦截请求，不是 npm 安装失败。处理方式是在 ~/.srt-settings.json 的 network 配置中，把确实需要访问的域名加入允许列表，然后重新运行同一个 srt 命令。若目标不需要联网，则保留拦截即可。

官方完整 settings 示例（注意 network 与 filesystem 都是必填段，缺字段会让校验失败）：

{
  "filesystem": {
    "denyRead": [],
    "allowWrite": ["."],
    "denyWrite": ["~/sensitive-folder"]
  },
  "network": {
    "allowedDomains": [],
    "deniedDomains": []
  }
}

写入 ~/.srt-settings.json 后生效；不放这个文件时 srt 用内置默认：无网络访问、默认写路径之外不可写、读不受限——这正是上面“没配域名就被拦”的原因。自定义路径用 srt --settings /path/to/srt-settings.json。

各平台依赖与验证：macOS 依赖系统自带的 sandbox-exec（无需另装）；Linux 需要 bubblewrap（Debian/Ubuntu 一般 sudo apt install bubblewrap——发行版包管理通用做法）；Windows 用系统自带机制（srt-sandbox 本地用户 + WFP），无需第三方依赖。验证命令通用：

srt "echo hello"        # 应输出 Running: echo hello 与 hello
srt --debug curl https://example.com   # 被拦时看 debug 日志定位是网络还是文件系统

`Operation not permitted`

文件读取出现该提示，表示沙箱阻止了当前进程访问指定路径。先判断命令是否必须读取该文件：不需要就维持阻止；确实需要时，再把对应文件或目录加入允许读取范围。

不要为了让报错消失而直接关闭整套沙箱。对于 Agent、MCP 服务和包含凭据的目录，应保留默认限制，只为当前任务添加最小权限。

怎么算安装成功

完成安装后，应同时满足三个可观察结果：终端能够找到 srt；读取当前目录文件时能看到 Running: 和文件内容；读取受限文件或访问未放行域名时出现明确的 Operation not permitted 或 Connection blocked by network allowlist。

如果三项都成立，说明 npm 包、srt 命令、操作系统沙箱和网络代理已经共同生效。若只有普通命令能运行、MCP 服务仍能直接访问敏感目录，则还没有真正经过 srt。

官方入口与后续核查

安装命令、能力说明和配置示例以 Anthropic sandbox-runtime 官方仓库为准。仓库采用 Apache-2.0 许可证，当前同时公开 Issues 和 Pull Requests；研究预览阶段出现配置差异时，可先搜索仓库中的 srt-settings、目标系统平台和具体报错。

如果改用 Homebrew 或源码方式，务必核对 LearnAgent 沙箱教程中使用的仓库地址与当前官方仓库是否一致。遇到命令层面的异常，再结合 GitHub Issues 提交可复现命令、系统版本和完整输出；提交前先删除令牌、私有路径及敏感目录名称。

参考来源

crates.io: Rust Package Registry – crates

# AI # 知识

评论区

0 条评论

登录后可评论。