返回更新列表
新发布Jul 21, 2026

sandbox-runtime v0.0.66

一个轻量级沙盒工具，用于在操作系统级别对任意进程强制执行文件系统和网络限制，无需使用容器。

分享

Anthropic Sandbox Runtime (srt)

一个轻量级沙箱工具，用于在操作系统层面强制对任意进程实施文件系统和网络限制，无需容器。

srt 使用原生操作系统沙箱原语（macOS 上的 sandbox-exec，Linux 上的 bubblewrap）以及基于代理的网络过滤。它可用于对代理、本地 MCP 服务器、bash 命令和任意进程的行为进行沙箱化。

Beta 研究预览版

Sandbox Runtime 是为 Claude Code 开发的研究预览版，旨在实现更安全的 AI 代理。它作为早期开源预览版发布，以帮助更广泛的生态系统构建更安全的代理系统。由于这是早期研究预览版，API 和配置格式可能会发生变化。我们欢迎反馈和贡献，以让 AI 代理默认更安全！

安装```bash

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

## 基本用法```bash
# Network restrictions
$ srt "curl anthropic.com"
Running: curl anthropic.com
<html>...</html>  # Request succeeds

$ srt "curl example.com"
Running: curl example.com
Connection blocked by network allowlist  # Request blocked

# Filesystem restrictions
$ srt "cat README.md"
Running: cat README.md
# Anthropic Sandb...  # Current directory access allowed

$ srt "cat ~/.ssh/id_rsa"
Running: cat ~/.ssh/id_rsa
cat: /Users/ollie/.ssh/id_rsa: Operation not permitted  # Specific file blocked

概述

此包提供了一个独立的沙箱实现，既可作为 CLI 工具使用，也可作为库使用。它采用默认安全的设计理念，针对常见的开发者使用场景量身定制：进程以最小权限启动，您只需显式地打开所需的缺口。

核心能力：

  • 网络限制：控制可通过 HTTP/HTTPS 及其他协议访问的主机/域名
  • 文件系统限制：控制可读取/写入的文件/目录
  • Unix 套接字限制：控制对本地 IPC 套接字的访问
  • 违规监控：在 macOS 上，接入系统的沙箱违规日志存储以获取实时警报

使用案例：沙箱化 MCP 服务器

一个关键用例是对模型上下文协议（MCP）服务器进行沙箱化，以限制其能力。例如，要对文件系统 MCP 服务器进行沙箱化：

不使用沙箱（.mcp.json）：```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] } } }

**使用沙箱**（`.mcp.json`）：```json
{
  "mcpServers": {
    "filesystem": {
      "command": "srt",
      "args": ["npx", "-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

然后在 ~/.srt-settings.json 中配置限制：```json { "filesystem": { "denyRead": [], "allowWrite": ["."], "denyWrite": ["~/sensitive-folder"] }, "network": { "allowedDomains": [], "deniedDomains": [] } }

现在 MCP 服务器将被阻止写入被拒绝的路径：```
> Write a file to ~/sensitive-folder
✗ Error: EPERM: operation not permitted, open '/Users/ollie/sensitive-folder/test.txt'

工作原理

该沙箱使用操作系统级原语来强制执行适用于整个进程树的限制：

  • macOS：使用 sandbox-exec 配合动态生成的 Seatbelt 配置文件
  • Linux：使用 bubblewrap 进行容器化，并实现网络命名空间隔离
  • Windows：在专用的 srt-sandbox 本地用户账户下运行沙箱进程，并使用以该账户的 SID 为键的 Windows 筛选平台 出站防护，以及在工作树上的每会话显式 ACE

0d1c612947c798aef48e6ab4beb7e8544da9d41a-4096x2305

双重隔离模型

有效的沙箱化需要同时实现文件系统和网络隔离。如果没有文件隔离，被攻陷的进程可能会窃取 SSH 密钥或其他敏感文件。如果没有网络隔离，进程可能逃逸沙箱并获得不受限制的网络访问。

文件系统隔离 强制执行读和写限制：

  • 读（先拒绝后允许模式）：默认情况下，允许在所有位置进行读取访问。你可以拒绝大范围区域（例如 /Users），然后重新允许其中的特定路径（例如 .）。allowRead 优先于 denyRead——这与写操作相反，在写操作中 denyWrite 优先于 allowWrite。比其所在的 allowRead 区域更具体的 denyRead 条目（例如 denyRead: ["**/.env"] 或 ["./secrets"] 配合 allowRead: ["."]）仍然保持拒绝状态。
  • 写（仅允许模式）：默认情况下，拒绝在所有位置进行写入访问。你必须显式允许路径（例如 .、/tmp）。空的允许列表意味着没有写入访问权限。

网络隔离（仅允许模式）：默认情况下，拒绝所有网络访问。你必须显式允许域名。空的 allowedDomains 列表意味着没有网络访问权限。网络流量通过运行在主机上的代理服务器进行路由：

  • Linux：请求通过 Unix 域套接字经由文件系统进行路由。沙箱进程的网络命名空间被完全移除，因此所有网络流量必须通过运行在主机上的代理（监听绑定挂载到沙箱中的 Unix 套接字）

  • macOS：Seatbelt 配置文件仅允许与特定 localhost 端口通信。代理监听此端口，为所有网络访问创建受控通道

  • Windows：机器范围的 WFP 筛选器集阻止源自 srt-sandbox 账户的所有出站连接，但到代理端口范围的环回连接除外。代理在该范围内监听，为所有网络访问创建受控通道

HTTP/HTTPS（通过 HTTP 代理）和其他 TCP 流量（通过 SOCKS5 代理）均由这些代理进行中介，这些代理强制执行你的域名允许列表和拒绝列表。

有关 Claude Code 中沙箱化的更多详细信息，请参阅：

架构```

src/ ├── index.ts # Library exports ├── cli.ts # CLI entrypoint (srt command) ├── utils/ # Shared utilities │ ├── debug.ts # Debug logging │ ├── settings.ts # Settings reader (permissions + sandbox config) │ ├── platform.ts # Platform detection │ └── exec.ts # Command execution utilities └── sandbox/ # Sandbox implementation ├── sandbox-manager.ts # Main sandbox manager ├── sandbox-schemas.ts # Zod schemas for validation ├── sandbox-violation-store.ts # Violation tracking ├── sandbox-utils.ts # Shared sandbox utilities ├── http-proxy.ts # HTTP/HTTPS proxy for network filtering ├── socks-proxy.ts # SOCKS5 proxy for network filtering ├── linux-sandbox-utils.ts # Linux bubblewrap sandboxing ├── macos-sandbox-utils.ts # macOS sandbox-exec sandboxing └── windows-sandbox-utils.ts # Windows srt-win sandboxing

## 用法

### 作为 CLI 工具

`srt` 命令（Anthropic Sandbox Runtime）用安全边界包装任意命令：```bash
# Run a command in the sandbox
srt echo "hello world"

# With debug logging
srt --debug curl https://example.com

# Specify custom settings file
srt --settings /path/to/srt-settings.json npm install

作为库使用```typescript

import { SandboxManager, type SandboxRuntimeConfig, } from '@anthropic-ai/sandbox-runtime' import { spawn } from 'child_process'

// Define your sandbox configuration const config: SandboxRuntimeConfig = { network: { allowedDomains: ['example.com', 'api.github.com'], deniedDomains: [], }, filesystem: { denyRead: ['~/.ssh'], allowWrite: ['.', '/tmp'], denyWrite: ['.env'], }, }

// Initialize the sandbox (starts proxy servers, etc.) await SandboxManager.initialize(config)

// Wrap a command with sandbox restrictions const sandboxedCommand = await SandboxManager.wrapWithSandbox( 'curl https://example.com', )

// Execute the sandboxed command const child = spawn(sandboxedCommand, { shell: true, stdio: 'inherit' })

// Handle exit and cleanup after child process completes child.on('exit', async code => { console.log(Command exited with code ${code}) // Cleanup when done (optional, happens automatically on process exit) await SandboxManager.reset() })

**违规归因（`commandId` / `commandText`）。** 在包装命令运行期间观察到的违规（seatbelt 日志行、seccomp 事件、代理拒绝）会存储在一个归因键下，而 `annotateStderrWithSandboxFailures(key, stderr)` / `getViolationsForCommand(key)` 会通过同一个键来查找它们。默认情况下，该键就是被包装的字符串本身。传入一个不透明的每次调用 `commandId`（例如工具使用 id）来以此作为键——推荐这样做：键会比较其前 100 个字符，因此共享前缀的长命令否则会交叉归因，并且相同文本的重新运行会继承先前运行的事件。如果你*执行*的字符串不是该调用*所代表*的命令（例如你包装了一个组装好的 `source <snapshot> && eval '<cmd>'`），还要传入 `commandText: '<cmd>'`：它是 `ignoreViolations` 命令模式所匹配的对象，也是每个违规报告为其 `command` 的内容。```typescript
const wrapped = await SandboxManager.wrapWithSandbox(
  assembledCommand, // what actually runs
  undefined,
  undefined,
  undefined,
  { commandId: invocationId, commandText: rawCommand },
)
// ... run it ...
const annotated = SandboxManager.annotateStderrWithSandboxFailures(invocationId, stderr)

可用的导出```typescript

// Main sandbox manager export { SandboxManager } from '@anthropic-ai/sandbox-runtime'

// Violation tracking export { SandboxViolationStore } from '@anthropic-ai/sandbox-runtime'

// TypeScript types export type { SandboxRuntimeConfig, NetworkConfig, FilesystemConfig, IgnoreViolationsConfig, SandboxAskCallback, FsReadRestrictionConfig, FsWriteRestrictionConfig, NetworkRestrictionConfig, } from '@anthropic-ai/sandbox-runtime'

## 配置

### 设置文件位置
阅读更多

分类

防御工具容器安全动态分析 (沙盒)配置审计安全虚拟化网络安全事件响应