[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-anthropic-experimental--sandbox-runtime":3,"tool-anthropic-experimental--sandbox-runtime":62},[4,18,26,36,46,54],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",159636,2,"2026-04-17T23:33:34",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":42,"last_commit_at":43,"category_tags":44,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,45],"插件",{"id":47,"name":48,"github_repo":49,"description_zh":50,"stars":51,"difficulty_score":32,"last_commit_at":52,"category_tags":53,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":55,"name":56,"github_repo":57,"description_zh":58,"stars":59,"difficulty_score":32,"last_commit_at":60,"category_tags":61,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[45,13,15,14],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":77,"owner_email":77,"owner_twitter":77,"owner_website":78,"owner_url":79,"languages":80,"stars":89,"forks":90,"last_commit_at":91,"license":92,"difficulty_score":32,"env_os":93,"env_gpu":94,"env_ram":94,"env_deps":95,"category_tags":101,"github_topics":77,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":102,"updated_at":103,"faqs":104,"releases":105},8794,"anthropic-experimental\u002Fsandbox-runtime","sandbox-runtime","A lightweight sandboxing tool for enforcing filesystem and network restrictions on arbitrary processes at the OS level, without requiring a container.","sandbox-runtime 是 Anthropic 推出的一款轻量级沙箱工具，旨在操作系统层面为任意进程强制实施文件系统和网络访问限制，且无需依赖传统的容器技术。它主要解决了 AI 智能体、本地服务或脚本在运行时可能意外泄露敏感数据（如 SSH 密钥）或发起未授权网络连接的安全隐患，通过“默认安全”的理念，让进程仅在明确授权的范围内活动。\n\n这款工具特别适合开发者、研究人员以及致力于构建安全 AI 代理系统的工程师使用。无论是隔离本地 MCP 服务器、限制 Bash 命令权限，还是测试不受信任的代码片段，sandbox-runtime 都能提供可靠的防护边界。\n\n其核心技术亮点在于巧妙利用了操作系统的原生沙箱机制：在 macOS 上动态生成 Seatbelt 配置文件调用 `sandbox-exec`，而在 Linux 上则借助 `bubblewrap` 实现命名空间隔离。此外，它还支持基于代理的网络过滤和 Unix 套接字访问控制，并能实时监控系统违规日志。作为一个开源的研究预览项目，sandbox-runtime 正帮助社区以更低的成本构建默认更安全的智能应用生态。","# Anthropic Sandbox Runtime (srt)\n\nA lightweight sandboxing tool for enforcing filesystem and network restrictions on arbitrary processes at the OS level, without requiring a container.\n\n`srt` uses native OS sandboxing primitives (`sandbox-exec` on macOS, `bubblewrap` on Linux) and proxy-based network filtering. It can be used to sandbox the behaviour of agents, local MCP servers, bash commands and arbitrary processes.\n\n> **Beta Research Preview**\n>\n> The Sandbox Runtime is a research preview developed for [Claude Code](https:\u002F\u002Fwww.claude.com\u002Fproduct\u002Fclaude-code) to enable safer AI agents. It's being made available as an early open source preview to help the broader ecosystem build more secure agentic systems. As this is an early research preview, APIs and configuration formats may evolve. We welcome feedback and contributions to make AI agents safer by default!\n\n## Installation\n\n```bash\nnpm install -g @anthropic-ai\u002Fsandbox-runtime\n```\n\n## Basic Usage\n\n```bash\n# Network restrictions\n$ srt \"curl anthropic.com\"\nRunning: curl anthropic.com\n\u003Chtml>...\u003C\u002Fhtml>  # Request succeeds\n\n$ srt \"curl example.com\"\nRunning: curl example.com\nConnection blocked by network allowlist  # Request blocked\n\n# Filesystem restrictions\n$ srt \"cat README.md\"\nRunning: cat README.md\n# Anthropic Sandb...  # Current directory access allowed\n\n$ srt \"cat ~\u002F.ssh\u002Fid_rsa\"\nRunning: cat ~\u002F.ssh\u002Fid_rsa\ncat: \u002FUsers\u002Follie\u002F.ssh\u002Fid_rsa: Operation not permitted  # Specific file blocked\n```\n\n## Overview\n\nThis package provides a standalone sandbox implementation that can be used as both a CLI tool and a library. It's designed with a **secure-by-default** philosophy tailored for common developer use cases: processes start with minimal access, and you explicitly poke only the holes you need.\n\n**Key capabilities:**\n\n- **Network restrictions**: Control which hosts\u002Fdomains can be accessed via HTTP\u002FHTTPS and other protocols\n- **Filesystem restrictions**: Control which files\u002Fdirectories can be read\u002Fwritten\n- **Unix socket restrictions**: Control access to local IPC sockets\n- **Violation monitoring**: On macOS, tap into the system's sandbox violation log store for real-time alerts\n\n### Example Use Case: Sandboxing MCP Servers\n\nA key use case is sandboxing Model Context Protocol (MCP) servers to restrict their capabilities. For example, to sandbox the filesystem MCP server:\n\n**Without sandboxing** (`.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\"]\n    }\n  }\n}\n```\n\n**With sandboxing** (`.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"srt\",\n      \"args\": [\"npx\", \"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\"]\n    }\n  }\n}\n```\n\nThen configure restrictions in `~\u002F.srt-settings.json`:\n\n```json\n{\n  \"filesystem\": {\n    \"denyRead\": [],\n    \"allowWrite\": [\".\"],\n    \"denyWrite\": [\"~\u002Fsensitive-folder\"]\n  },\n  \"network\": {\n    \"allowedDomains\": [],\n    \"deniedDomains\": []\n  }\n}\n```\n\nNow the MCP server will be blocked from writing to the denied path:\n\n```\n> Write a file to ~\u002Fsensitive-folder\n✗ Error: EPERM: operation not permitted, open '\u002FUsers\u002Follie\u002Fsensitive-folder\u002Ftest.txt'\n```\n\n## How It Works\n\nThe sandbox uses OS-level primitives to enforce restrictions that apply to the entire process tree:\n\n- **macOS**: Uses `sandbox-exec` with dynamically generated [Seatbelt profiles](https:\u002F\u002Freverse.put.as\u002Fwp-content\u002Fuploads\u002F2011\u002F09\u002FApple-Sandbox-Guide-v1.0.pdf)\n- **Linux**: Uses [bubblewrap](https:\u002F\u002Fgithub.com\u002Fcontainers\u002Fbubblewrap) for containerization with network namespace isolation\n\n![0d1c612947c798aef48e6ab4beb7e8544da9d41a-4096x2305](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F76c838a9-19ef-4d0b-90bb-cbe1917b3551)\n\n### Dual Isolation Model\n\nBoth filesystem and network isolation are required for effective sandboxing. Without file isolation, a compromised process could exfiltrate SSH keys or other sensitive files. Without network isolation, a process could escape the sandbox and gain unrestricted network access.\n\n**Filesystem Isolation** enforces read and write restrictions:\n\n- **Read** (deny-then-allow pattern): By default, read access is allowed everywhere. You can deny broad regions (e.g., `\u002FUsers`) and then re-allow specific paths within them (e.g., `.`). `allowRead` takes precedence over `denyRead` — the opposite of write, where `denyWrite` takes precedence over `allowWrite`.\n- **Write** (allow-only pattern): By default, write access is denied everywhere. You must explicitly allow paths (e.g., `.`, `\u002Ftmp`). An empty allow list means no write access.\n\n**Network Isolation** (allow-only pattern): By default, all network access is denied. You must explicitly allow domains. An empty allowedDomains list means no network access. Network traffic is routed through proxy servers running on the host:\n\n- **Linux**: Requests are routed via the filesystem over a Unix domain socket. The network namespace of the sandboxed process is removed entirely, so all network traffic must go through the proxies running on the host (listening on Unix sockets that are bind-mounted into the sandbox)\n\n- **macOS**: The Seatbelt profile allows communication only to a specific localhost port. The proxies listen on this port, creating a controlled channel for all network access\n\nBoth HTTP\u002FHTTPS (via HTTP proxy) and other TCP traffic (via SOCKS5 proxy) are mediated by these proxies, which enforce your domain allowlists and denylists.\n\nFor more details on sandboxing in Claude Code, see:\n\n- [Claude Code Sandboxing Documentation](https:\u002F\u002Fdocs.claude.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Fsandboxing)\n- [Beyond Permission Prompts: Making Claude Code More Secure and Autonomous](https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fclaude-code-sandboxing)\n\n## Architecture\n\n```\nsrc\u002F\n├── index.ts                  # Library exports\n├── cli.ts                    # CLI entrypoint (srt command)\n├── utils\u002F                    # Shared utilities\n│   ├── debug.ts             # Debug logging\n│   ├── settings.ts          # Settings reader (permissions + sandbox config)\n│   ├── platform.ts          # Platform detection\n│   └── exec.ts              # Command execution utilities\n└── sandbox\u002F                  # Sandbox implementation\n    ├── sandbox-manager.ts    # Main sandbox manager\n    ├── sandbox-schemas.ts    # Zod schemas for validation\n    ├── sandbox-violation-store.ts # Violation tracking\n    ├── sandbox-utils.ts      # Shared sandbox utilities\n    ├── http-proxy.ts         # HTTP\u002FHTTPS proxy for network filtering\n    ├── socks-proxy.ts        # SOCKS5 proxy for network filtering\n    ├── linux-sandbox-utils.ts # Linux bubblewrap sandboxing\n    └── macos-sandbox-utils.ts # macOS sandbox-exec sandboxing\n```\n\n## Usage\n\n### As a CLI tool\n\nThe `srt` command (Anthropic Sandbox Runtime) wraps any command with security boundaries:\n\n```bash\n# Run a command in the sandbox\nsrt echo \"hello world\"\n\n# With debug logging\nsrt --debug curl https:\u002F\u002Fexample.com\n\n# Specify custom settings file\nsrt --settings \u002Fpath\u002Fto\u002Fsrt-settings.json npm install\n```\n\n### As a library\n\n```typescript\nimport {\n  SandboxManager,\n  type SandboxRuntimeConfig,\n} from '@anthropic-ai\u002Fsandbox-runtime'\nimport { spawn } from 'child_process'\n\n\u002F\u002F Define your sandbox configuration\nconst config: SandboxRuntimeConfig = {\n  network: {\n    allowedDomains: ['example.com', 'api.github.com'],\n    deniedDomains: [],\n  },\n  filesystem: {\n    denyRead: ['~\u002F.ssh'],\n    allowWrite: ['.', '\u002Ftmp'],\n    denyWrite: ['.env'],\n  },\n}\n\n\u002F\u002F Initialize the sandbox (starts proxy servers, etc.)\nawait SandboxManager.initialize(config)\n\n\u002F\u002F Wrap a command with sandbox restrictions\nconst sandboxedCommand = await SandboxManager.wrapWithSandbox(\n  'curl https:\u002F\u002Fexample.com',\n)\n\n\u002F\u002F Execute the sandboxed command\nconst child = spawn(sandboxedCommand, { shell: true, stdio: 'inherit' })\n\n\u002F\u002F Handle exit and cleanup after child process completes\nchild.on('exit', async code => {\n  console.log(`Command exited with code ${code}`)\n  \u002F\u002F Cleanup when done (optional, happens automatically on process exit)\n  await SandboxManager.reset()\n})\n```\n\n#### Available exports\n\n```typescript\n\u002F\u002F Main sandbox manager\nexport { SandboxManager } from '@anthropic-ai\u002Fsandbox-runtime'\n\n\u002F\u002F Violation tracking\nexport { SandboxViolationStore } from '@anthropic-ai\u002Fsandbox-runtime'\n\n\u002F\u002F TypeScript types\nexport type {\n  SandboxRuntimeConfig,\n  NetworkConfig,\n  FilesystemConfig,\n  IgnoreViolationsConfig,\n  SandboxAskCallback,\n  FsReadRestrictionConfig,\n  FsWriteRestrictionConfig,\n  NetworkRestrictionConfig,\n} from '@anthropic-ai\u002Fsandbox-runtime'\n```\n\n## Configuration\n\n### Settings File Location\n\nBy default, the sandbox runtime looks for configuration at `~\u002F.srt-settings.json`. You can specify a custom path using the `--settings` flag:\n\n```bash\nsrt --settings \u002Fpath\u002Fto\u002Fsrt-settings.json \u003Ccommand>\n```\n\n### Complete Configuration Example\n\n```json\n{\n  \"network\": {\n    \"allowedDomains\": [\n      \"github.com\",\n      \"*.github.com\",\n      \"lfs.github.com\",\n      \"api.github.com\",\n      \"npmjs.org\",\n      \"*.npmjs.org\"\n    ],\n    \"deniedDomains\": [\"malicious.com\"],\n    \"allowUnixSockets\": [\"\u002Fvar\u002Frun\u002Fdocker.sock\"],\n    \"allowLocalBinding\": false\n  },\n  \"filesystem\": {\n    \"denyRead\": [\"~\u002F.ssh\"],\n    \"allowRead\": [],\n    \"allowWrite\": [\".\", \"src\u002F\", \"test\u002F\", \"\u002Ftmp\"],\n    \"denyWrite\": [\".env\", \"config\u002Fproduction.json\"]\n  },\n  \"ignoreViolations\": {\n    \"*\": [\"\u002Fusr\u002Fbin\", \"\u002FSystem\"],\n    \"git push\": [\"\u002Fusr\u002Fbin\u002Fnc\"],\n    \"npm\": [\"\u002Fprivate\u002Ftmp\"]\n  },\n  \"enableWeakerNestedSandbox\": false,\n  \"enableWeakerNetworkIsolation\": false\n}\n```\n\n### Configuration Options\n\n#### Network Configuration\n\nUses an **allow-only pattern** - all network access is denied by default.\n\n- `network.allowedDomains` - Array of allowed domains (supports wildcards like `*.example.com`). Empty array = no network access.\n- `network.deniedDomains` - Array of denied domains (checked first, takes precedence over allowedDomains)\n- `network.allowLocalBinding` - Allow binding to local ports (boolean, default: false)\n\n**Unix Socket Settings** (platform-specific behavior):\n\n| Setting                        | macOS                     | Linux                                    |\n| ------------------------------ | ------------------------- | ---------------------------------------- |\n| `allowUnixSockets: string[]`   | Allowlist of socket paths | _Ignored_ (seccomp can't filter by path) |\n| `allowAllUnixSockets: boolean` | Allow all sockets         | Disable seccomp blocking                 |\n\nUnix sockets are **blocked by default** on both platforms.\n\n- **macOS**: Use `allowUnixSockets` to allow specific paths (e.g., `[\"\u002Fvar\u002Frun\u002Fdocker.sock\"]`), or `allowAllUnixSockets: true` to allow all.\n- **Linux**: Blocking uses seccomp filters (x64\u002Farm64 only). If seccomp isn't available, sockets are unrestricted and a warning is shown. Use `allowAllUnixSockets: true` to explicitly disable blocking.\n\n#### Filesystem Configuration\n\nUses two different patterns:\n\n**Read restrictions** (deny-then-allow pattern) - all reads allowed by default:\n\n- `filesystem.denyRead` - Array of paths to deny read access. Empty array = full read access.\n- `filesystem.allowRead` - Array of paths to re-allow read access within denied regions (takes precedence over denyRead). **Note:** this is the opposite of write, where `denyWrite` takes precedence over `allowWrite`.\n\n**Write restrictions** (allow-only pattern) - all writes denied by default:\n\n- `filesystem.allowWrite` - Array of paths to allow write access. Empty array = no write access.\n- `filesystem.denyWrite` - Array of paths to deny write access within allowed paths (takes precedence over allowWrite)\n\n**Path Syntax (macOS):**\n\nPaths support git-style glob patterns on macOS, similar to `.gitignore` syntax:\n\n- `*` - Matches any characters except `\u002F` (e.g., `*.ts` matches `foo.ts` but not `foo\u002Fbar.ts`)\n- `**` - Matches any characters including `\u002F` (e.g., `src\u002F**\u002F*.ts` matches all `.ts` files in `src\u002F`)\n- `?` - Matches any single character except `\u002F` (e.g., `file?.txt` matches `file1.txt`)\n- `[abc]` - Matches any character in the set (e.g., `file[0-9].txt` matches `file3.txt`)\n\nExamples:\n\n- `\"allowWrite\": [\"src\u002F\"]` - Allow write to entire `src\u002F` directory\n- `\"allowWrite\": [\"src\u002F**\u002F*.ts\"]` - Allow write to all `.ts` files in `src\u002F` and subdirectories\n- `\"denyRead\": [\"~\u002F.ssh\"]` - Deny read to SSH directory\n- `\"denyRead\": [\"\u002FUsers\"], \"allowRead\": [\".\"]` - Deny read to all of `\u002FUsers`, but re-allow the current directory\n- `\"denyWrite\": [\".env\"]` - Deny write to `.env` file (even if current directory is allowed)\n\n**Path Syntax (Linux):**\n\n**Linux currently does not support glob matching.** Use literal paths only:\n\n- `\"allowWrite\": [\"src\u002F\"]` - Allow write to `src\u002F` directory\n- `\"denyRead\": [\"\u002Fhome\u002Fuser\u002F.ssh\"]` - Deny read to SSH directory\n- `\"denyRead\": [\"\u002Fhome\"], \"allowRead\": [\".\"]` - Deny read to all of `\u002Fhome`, but re-allow the current directory\n\n**All platforms:**\n\n- Paths can be absolute (e.g., `\u002Fhome\u002Fuser\u002F.ssh`) or relative to the current working directory (e.g., `.\u002Fsrc`)\n- `~` expands to the user's home directory\n\n#### Other Configuration\n\n- `ignoreViolations` - Object mapping command patterns to arrays of paths where violations should be ignored\n- `enableWeakerNestedSandbox` - Enable weaker sandbox mode for Docker environments (boolean, default: false)\n- `enableWeakerNetworkIsolation` - Allow access to `com.apple.trustd.agent` in the macOS sandbox (boolean, default: false). This is needed for Go programs (`gh`, `gcloud`, `terraform`, `kubectl`, etc.) to verify TLS certificates when using `httpProxyPort` with a MITM proxy and custom CA. **Security warning:** enabling this opens a potential data exfiltration vector through the trustd service.\n\n### Common Configuration Recipes\n\n**Allow GitHub access** (all necessary endpoints):\n\n```json\n{\n  \"network\": {\n    \"allowedDomains\": [\n      \"github.com\",\n      \"*.github.com\",\n      \"lfs.github.com\",\n      \"api.github.com\"\n    ],\n    \"deniedDomains\": []\n  },\n  \"filesystem\": {\n    \"denyRead\": [],\n    \"allowWrite\": [\".\"],\n    \"denyWrite\": []\n  }\n}\n```\n\n**Restrict to specific directories:**\n\n```json\n{\n  \"network\": {\n    \"allowedDomains\": [],\n    \"deniedDomains\": []\n  },\n  \"filesystem\": {\n    \"denyRead\": [\"~\u002F.ssh\"],\n    \"allowWrite\": [\".\", \"src\u002F\", \"test\u002F\"],\n    \"denyWrite\": [\".env\", \"secrets\u002F\"]\n  }\n}\n```\n\n**Workspace-only filesystem access** (deny reads outside the workspace):\n\n```json\n{\n  \"network\": {\n    \"allowedDomains\": [],\n    \"deniedDomains\": []\n  },\n  \"filesystem\": {\n    \"denyRead\": [\"\u002FUsers\"],\n    \"allowRead\": [\".\"],\n    \"allowWrite\": [\".\"],\n    \"denyWrite\": []\n  }\n}\n```\n\nThis denies reading anything under `\u002FUsers` (or `\u002Fhome` on Linux), then re-allows the current working directory. System paths (`\u002Fusr`, `\u002Flib`, etc.) remain readable.\n\n### Common Issues and Tips\n\n**Running Jest:** Use `--no-watchman` flag to avoid sandbox violations:\n\n```bash\nsrt \"jest --no-watchman\"\n```\n\nWatchman accesses files outside the sandbox boundaries, which will trigger permission errors. Disabling it allows Jest to run with the built-in file watcher instead.\n\n## Platform Support\n\n- **macOS**: Uses `sandbox-exec` with custom profiles (no additional dependencies)\n- **Linux**: Uses `bubblewrap` (bwrap) for containerization\n- **Windows**: Not yet supported\n\n### Platform-Specific Dependencies\n\n**Linux requires:**\n\n- `bubblewrap` - Container runtime\n  - Ubuntu\u002FDebian: `apt-get install bubblewrap`\n  - Fedora: `dnf install bubblewrap`\n  - Arch: `pacman -S bubblewrap`\n- `socat` - Socket relay for proxy bridging\n  - Ubuntu\u002FDebian: `apt-get install socat`\n  - Fedora: `dnf install socat`\n  - Arch: `pacman -S socat`\n- `ripgrep` - Fast search tool for deny path detection\n  - Ubuntu\u002FDebian: `apt-get install ripgrep`\n  - Fedora: `dnf install ripgrep`\n  - Arch: `pacman -S ripgrep`\n\n**Ubuntu 24.04+ note:** These releases enable `kernel.apparmor_restrict_unprivileged_userns` by default, which allows `unshare(CLONE_NEWUSER)` but strips capabilities from the resulting namespace. Both bubblewrap and the seccomp isolation layer need capability-bearing user namespaces. Disable the restriction with:\n\n```bash\nsudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0\n```\n\nor add an AppArmor profile that grants `userns` to the relevant binaries.\n\n**Optional Linux dependencies (for seccomp fallback):**\n\nThe package includes pre-generated seccomp BPF filters for x86-64 and arm architectures. These dependencies are only needed if you are on a different architecture where pre-generated filters are not available:\n\n- `gcc` or `clang` - C compiler\n- `libseccomp-dev` - Seccomp library development files\n  - Ubuntu\u002FDebian: `apt-get install gcc libseccomp-dev`\n  - Fedora: `dnf install gcc libseccomp-devel`\n  - Arch: `pacman -S gcc libseccomp`\n\n**macOS requires:**\n\n- `ripgrep` - Fast search tool for deny path detection\n  - Install via Homebrew: `brew install ripgrep`\n  - Or download from: https:\u002F\u002Fgithub.com\u002FBurntSushi\u002Fripgrep\u002Freleases\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests\nnpm test\n\n# Type checking\nnpm run typecheck\n\n# Lint code\nnpm run lint\n\n# Format code\nnpm run format\n```\n\n### Building Seccomp Binaries\n\nThe BPF filter and `apply-seccomp` loader are compiled from C source in `vendor\u002Fseccomp-src\u002F` via `npm run build:seccomp` (Linux only; needs `gcc` and `libseccomp-dev`). CI runs it before tests on each Linux arch, and the release workflow builds both arches and bundles them into the published package.\n\n## Implementation Details\n\n### Network Isolation Architecture\n\nThe sandbox runs HTTP and SOCKS5 proxy servers on the host machine that filter all network requests based on permission rules:\n\n1. **HTTP\u002FHTTPS Traffic**: An HTTP proxy server intercepts requests and validates them against allowed\u002Fdenied domains\n2. **Other Network Traffic**: A SOCKS5 proxy handles all other TCP connections (SSH, database connections, etc.)\n3. **Permission Enforcement**: The proxies enforce the `permissions` rules from your configuration\n\n**Platform-specific proxy communication:**\n\n- **Linux**: Requests are routed via the filesystem over Unix domain sockets (using `socat` for bridging). The network namespace is removed from the bubblewrap container, ensuring all network traffic must go through the proxies.\n\n- **macOS**: The Seatbelt profile allows communication only to specific localhost ports where the proxies listen. All other network access is blocked.\n\n### Filesystem Isolation\n\nFilesystem restrictions are enforced at the OS level:\n\n- **macOS**: Uses `sandbox-exec` with dynamically generated Seatbelt profiles that specify allowed read\u002Fwrite paths\n- **Linux**: Uses `bubblewrap` with bind mounts, marking directories as read-only or read-write based on configuration\n\n**Default filesystem permissions:**\n\n- **Read** (deny-then-allow): Allowed everywhere by default. You can deny broad regions, then re-allow specific paths within them. `allowRead` takes precedence over `denyRead`.\n\n  - Example: `denyRead: [\"~\u002F.ssh\"]` to block access to SSH keys\n  - Example: `denyRead: [\"\u002FUsers\"], allowRead: [\".\"]` to block all of `\u002FUsers` except the workspace\n  - Empty `denyRead: []` = full read access (nothing denied)\n\n- **Write** (allow-only): Denied everywhere by default. You must explicitly allow paths.\n  - Example: `allowWrite: [\".\", \"\u002Ftmp\"]` to allow writes to current directory and \u002Ftmp\n  - Empty `allowWrite: []` = no write access (nothing allowed)\n  - `denyWrite` creates exceptions within allowed paths (deny takes precedence)\n\n**Precedence is intentionally opposite for reads vs writes:** `allowRead` overrides `denyRead`, while `denyWrite` overrides `allowWrite`. This lets you carve out readable regions within denied areas, and carve out protected regions within writable areas.\n\n### Mandatory Deny Paths (Auto-Protected Files)\n\nCertain sensitive files and directories are **always blocked from writes**, even if they fall within an allowed write path. This provides defense-in-depth against sandbox escapes and configuration tampering.\n\n**Always-blocked files:**\n\n- Shell config files: `.bashrc`, `.bash_profile`, `.zshrc`, `.zprofile`, `.profile`\n- Git config files: `.gitconfig`, `.gitmodules`\n- Other sensitive files: `.ripgreprc`, `.mcp.json`\n\n**Always-blocked directories:**\n\n- IDE directories: `.vscode\u002F`, `.idea\u002F`\n- Claude config directories: `.claude\u002Fcommands\u002F`, `.claude\u002Fagents\u002F`\n- Git hooks and config: `.git\u002Fhooks\u002F`, `.git\u002Fconfig`\n\nThese paths are blocked automatically - you don't need to add them to `denyWrite`. For example, even with `allowWrite: [\".\"]`, writing to `.bashrc` or `.git\u002Fhooks\u002Fpre-commit` will fail:\n\n```bash\n$ srt 'echo \"malicious\" >> .bashrc'\n\u002Fbin\u002Fbash: .bashrc: Operation not permitted\n\n$ srt 'echo \"bad\" > .git\u002Fhooks\u002Fpre-commit'\n\u002Fbin\u002Fbash: .git\u002Fhooks\u002Fpre-commit: Operation not permitted\n```\n\n**Note (Linux):** On Linux, mandatory deny paths only block files that already exist. Non-existent files in these patterns cannot be blocked by bubblewrap's bind-mount approach. macOS uses glob patterns which block both existing and new files.\n\n**Linux search depth:** On Linux, the sandbox uses `ripgrep` to scan for dangerous files in subdirectories within allowed write paths. By default, it searches up to 3 levels deep for performance. You can configure this with `mandatoryDenySearchDepth`:\n\n```json\n{\n  \"mandatoryDenySearchDepth\": 5,\n  \"filesystem\": {\n    \"allowWrite\": [\".\"]\n  }\n}\n```\n\n- Default: `3` (searches up to 3 levels deep)\n- Range: `1` to `10`\n- Higher values provide more protection but slower performance\n- Files in CWD (depth 0) are always protected regardless of this setting\n\n### Unix Socket Restrictions (Linux)\n\nOn Linux, the sandbox uses **seccomp BPF (Berkeley Packet Filter)** to block Unix domain socket creation at the syscall level. This provides an additional layer of security to prevent processes from creating new Unix domain sockets for local IPC (unless explicitly allowed).\n\n**How it works:**\n\n1. **Baked-in BPF filter**: The package ships a static `apply-seccomp` binary for x64 and arm64 with the seccomp BPF filter compiled in. The filter is architecture-specific but libc-independent, so the binary works with both glibc and musl.\n\n2. **Runtime detection**: The sandbox automatically detects your system's architecture and uses the matching `apply-seccomp` binary.\n\n3. **Syscall filtering**: The BPF filter intercepts the `socket()` syscall and blocks creation of `AF_UNIX` sockets by returning `EPERM`. This prevents sandboxed code from creating new Unix domain sockets.\n\n4. **Two-stage application using apply-seccomp binary**:\n   - Outer bwrap creates the sandbox with filesystem, network, and PID namespace restrictions\n   - Network bridging processes (socat) start inside the sandbox (need Unix sockets)\n   - apply-seccomp creates a nested user+PID+mount namespace and remounts `\u002Fproc`\n   - Inside the nested namespace, apply-seccomp acts as PID 1 (non-dumpable init\u002Freaper)\n   - apply-seccomp forks, applies the seccomp filter via `prctl()`, and execs the user command\n   - User command runs with all sandbox restrictions plus Unix socket creation blocking\n\n**PID namespace isolation**: The nested PID namespace ensures the user command cannot see or address any process that runs without the seccomp filter (bwrap's init, the shell wrapper, or the socat helpers). This keeps the seccomp boundary intact regardless of `kernel.yama.ptrace_scope`, since unfiltered helpers are not reachable via `ptrace` or `\u002Fproc\u002FN\u002Fmem`. The inner PID 1 sets `PR_SET_DUMPABLE=0` so it is not ptraceable either. If nested namespace creation fails, apply-seccomp aborts rather than running without isolation.\n\n**Security limitations**: The filter blocks `socket(AF_UNIX, ...)` and the `io_uring_setup`\u002F`io_uring_enter`\u002F`io_uring_register` syscalls (the latter three because `IORING_OP_SOCKET` on Linux 5.19+ would otherwise bypass the `socket()` rule). It does not prevent operations on Unix socket file descriptors inherited from parent processes or passed via `SCM_RIGHTS`. For most sandboxing scenarios, blocking socket creation is sufficient to prevent unauthorized IPC.\n\n**Zero runtime dependencies**: Pre-built static apply-seccomp binaries and pre-generated BPF filters are included for x64 and arm64 architectures. No compilation tools or external dependencies required at runtime.\n\n**Architecture support**: x64 and arm64 are fully supported with pre-built binaries. Other architectures are not currently supported. To use sandboxing without Unix socket blocking on unsupported architectures, set `allowAllUnixSockets: true` in your configuration.\n\n### Violation Detection and Monitoring\n\nWhen a sandboxed process attempts to access a restricted resource:\n\n1. **Blocks the operation** at the OS level (returns `EPERM` error)\n2. **Logs the violation** (platform-specific mechanisms)\n3. **Notifies the user** (in Claude Code, this triggers a permission prompt)\n\n**macOS**: The sandbox runtime taps into macOS's system sandbox violation log store. This provides real-time notifications with detailed information about what was attempted and why it was blocked. This is the same mechanism Claude Code uses for violation detection.\n\n```bash\n# View sandbox violations in real-time\nlog stream --predicate 'process == \"sandbox-exec\"' --style syslog\n```\n\n**Linux**: Bubblewrap doesn't provide built-in violation reporting. Use `strace` to trace system calls and identify blocked operations:\n\n```bash\n# Trace all denied operations\nstrace -f srt \u003Cyour-command> 2>&1 | grep EPERM\n\n# Trace specific file operations\nstrace -f -e trace=open,openat,stat,access srt \u003Cyour-command> 2>&1 | grep EPERM\n\n# Trace network operations\nstrace -f -e trace=network srt \u003Cyour-command> 2>&1 | grep EPERM\n```\n\n### Advanced: Bring Your Own Proxy\n\nFor more sophisticated network filtering, you can configure the sandbox to use your own proxy instead of the built-in ones. This enables:\n\n- **Traffic inspection**: Use tools like [mitmproxy](https:\u002F\u002Fmitmproxy.org\u002F) to inspect and modify traffic\n- **Custom filtering logic**: Implement complex rules beyond simple domain allowlists\n- **Audit logging**: Log all network requests for compliance or debugging\n\n**Example with mitmproxy:**\n\n```bash\n# Start mitmproxy with custom filtering script\nmitmproxy -s custom_filter.py --listen-port 8888\n```\n\nNote: Custom proxy configuration is not yet supported in the new configuration format. This feature will be added in a future release.\n\n**Important security consideration:** Even with domain allowlists, exfiltration vectors may exist. For example, allowing `github.com` lets a process push to any repository. With a custom MITM proxy and proper certificate setup, you can inspect and filter specific API calls to prevent this.\n\n### Security Limitations\n\n- Network Sandboxing Limitations: The network filtering system operates by restricting the domains that processes are allowed to connect to. It does not otherwise inspect the traffic passing through the proxy and users are responsible for ensuring they only allow trusted domains in their policy.\n\n\u003CWarning>\nUsers should be aware of potential risks that come from allowing broad domains like `github.com` that may allow for data exfiltration. Also, in some cases it may be possible to bypass the network filtering through [domain fronting](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FDomain_fronting).   \n\u003C\u002FWarning>\n\n- Privilege Escalation via Unix Sockets: The `allowUnixSockets` configuration can inadvertently grant access to powerful system services that could lead to sandbox bypasses. For example, if it is used to allow access to `\u002Fvar\u002Frun\u002Fdocker.sock` this would effectively grant access to the host system through exploiting the docker socket. Users are encouraged to carefully consider any unix sockets that they allow through the sandbox.\n- Filesystem Permission Escalation: Overly broad filesystem write permissions can enable privilege escalation attacks. Allowing writes to directories containing executables in `$PATH`, system configuration directories, or user shell configuration files (`.bashrc`, `.zshrc`) can lead to code execution in different security contexts when other users or system processes access these files.\n- Linux Sandbox Strength: The Linux implementation provides strong filesystem and network isolation but includes an `enableWeakerNestedSandbox` mode that enables it to work inside of Docker environments without privileged namespaces. This option considerably weakens security and should only be used incases where additional isolation is otherwise enforced.\n- Weaker Network Isolation (macOS): The `enableWeakerNetworkIsolation` option re-enables access to `com.apple.trustd.agent`, which is needed for Go programs to verify TLS certificates via the macOS Security framework. This opens a potential data exfiltration vector through the trustd service and should only be enabled when Go TLS verification is required (e.g., when using `httpProxyPort` with a MITM proxy and custom CA).\n\n### Known Limitations and Future Work\n\n**Linux proxy bypass**: Currently uses environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`) to direct traffic through proxies. This works for most applications but may be ignored by programs that don't respect these variables, leading to them being unable to connect to the internet.\n\n**Future improvements:**\n\n- **Proxychains support**: Add support for `proxychains` with `LD_PRELOAD` on Linux to intercept network calls at a lower level, making bypass more difficult\n\n- **Linux violation monitoring**: Implement automatic `strace`-based violation detection for Linux, integrated with the violation store. Currently, Linux users must manually run `strace` to see violations, unlike macOS which has automatic violation monitoring via the system log store\n","# Anthropic 沙箱运行时 (srt)\n\n一种轻量级的沙箱工具，可在操作系统级别对任意进程强制实施文件系统和网络限制，而无需使用容器。\n\n`srt` 使用原生操作系统沙箱原语（macOS 上的 `sandbox-exec`，Linux 上的 `bubblewrap`）以及基于代理的网络过滤。它可以用于沙箱化智能体、本地 MCP 服务器、bash 命令和任意进程的行为。\n\n> **测试版研究预览**\n>\n> 沙箱运行时是为 [Claude Code](https:\u002F\u002Fwww.claude.com\u002Fproduct\u002Fclaude-code) 开发的研究预览版本，旨在实现更安全的 AI 智能体。我们将其作为早期开源预览版本提供，以帮助更广泛的生态系统构建更加安全的智能体系统。由于这仍处于早期研究阶段，API 和配置格式可能会发生变化。我们欢迎反馈和贡献，以使 AI 智能体在默认情况下更加安全！\n\n## 安装\n\n```bash\nnpm install -g @anthropic-ai\u002Fsandbox-runtime\n```\n\n## 基本用法\n\n```bash\n# 网络限制\n$ srt \"curl anthropic.com\"\n正在运行: curl anthropic.com\n\u003Chtml>...\u003C\u002Fhtml>  # 请求成功\n\n$ srt \"curl example.com\"\n正在运行: curl example.com\n连接被网络白名单阻止  # 请求被拦截\n\n# 文件系统限制\n$ srt \"cat README.md\"\n正在运行: cat README.md\n# Anthropic Sandb...  # 当前目录访问被允许\n\n$ srt \"cat ~\u002F.ssh\u002Fid_rsa\"\n正在运行: cat ~\u002F.ssh\u002Fid_rsa\ncat: \u002FUsers\u002Follie\u002F.ssh\u002Fid_rsa: 操作未被授权  # 特定文件被拦截\n```\n\n## 概述\n\n该软件包提供了一个独立的沙箱实现，既可用作命令行工具，也可作为库使用。它采用“默认安全”的设计理念，专为常见的开发者用例而设计：进程启动时仅具有最小权限，您只需显式地打开所需的访问通道。\n\n**关键功能：**\n\n- **网络限制**：控制可通过 HTTP\u002FHTTPS 及其他协议访问的主机\u002F域名\n- **文件系统限制**：控制可读\u002F写的文件\u002F目录\n- **Unix 套接字限制**：控制对本地 IPC 套接字的访问\n- **违规监控**：在 macOS 上，可接入系统的沙箱违规日志存储，以获取实时警报\n\n### 示例用例：MCP 服务器的沙箱化\n\n一个关键用例是将模型上下文协议 (MCP) 服务器进行沙箱化，以限制其能力。例如，要对文件系统 MCP 服务器进行沙箱化：\n\n**未沙箱化**（`.mcp.json`）：\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\"]\n    }\n  }\n}\n```\n\n**已沙箱化**（`.mcp.json`）：\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"srt\",\n      \"args\": [\"npx\", \"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\"]\n    }\n  }\n}\n```\n\n然后在 `~\u002F.srt-settings.json` 中配置限制：\n\n```json\n{\n  \"filesystem\": {\n    \"denyRead\": [],\n    \"allowWrite\": [\".\"],\n    \"denyWrite\": [\"~\u002Fsensitive-folder\"]\n  },\n  \"network\": {\n    \"allowedDomains\": [],\n    \"deniedDomains\": []\n  }\n}\n```\n\n现在 MCP 服务器将被阻止写入被拒绝的路径：\n\n```\n> 向 ~\u002Fsensitive-folder 写入文件\n✗ 错误：EPERM：操作未被授权，无法打开 '\u002FUsers\u002Follie\u002Fsensitive-folder\u002Ftest.txt'\n```\n\n## 工作原理\n\n该沙箱使用操作系统级别的原语来强制实施适用于整个进程树的限制：\n\n- **macOS**：使用 `sandbox-exec` 结合动态生成的 [Seatbelt 配置文件](https:\u002F\u002Freverse.put.as\u002Fwp-content\u002Fuploads\u002F2011\u002F09\u002FApple-Sandbox-Guide-v1.0.pdf)\n- **Linux**：使用 [bubblewrap](https:\u002F\u002Fgithub.com\u002Fcontainers\u002Fbubblewrap) 进行容器化，并结合网络命名空间隔离\n\n![0d1c612947c798aef48e6ab4beb7e8544da9d41a-4096x2305](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F76c838a9-19ef-4d0b-90bb-cbe1917b3551)\n\n### 双重隔离模型\n\n有效的沙箱化需要同时实现文件系统和网络隔离。如果没有文件隔离，被攻陷的进程可能会窃取 SSH 密钥或其他敏感文件。如果没有网络隔离，进程可能会逃出沙箱并获得不受限制的网络访问权限。\n\n**文件系统隔离** 强制实施读写限制：\n\n- **读取**（先禁止再允许模式）：默认情况下，所有位置都允许读取。您可以先禁止某些大范围区域（如 `\u002FUsers`），然后再重新允许其中的特定路径（如 `.`）。`allowRead` 的优先级高于 `denyRead`——与写入相反，后者中 `denyWrite` 的优先级高于 `allowWrite`。\n- **写入**（仅允许模式）：默认情况下，所有位置均禁止写入。您必须显式地允许某些路径（如 `.` 或 `\u002Ftmp`）。如果允许列表为空，则表示无写入权限。\n\n**网络隔离**（仅允许模式）：默认情况下，所有网络访问都被禁止。您必须显式地允许特定域名。如果 allowedDomains 列表为空，则表示无网络访问权限。网络流量会通过主机上运行的代理服务器路由：\n\n- **Linux**：请求通过文件系统经由 Unix 域套接字路由。被沙箱化的进程的网络命名空间会被完全移除，因此所有网络流量都必须经过主机上运行的代理（这些代理监听绑定到沙箱内的 Unix 套接字）。\n\n- **macOS**：Seatbelt 配置文件仅允许与特定的本地回环端口通信。代理监听该端口，从而为所有网络访问创建一个受控通道。\n\n无论是 HTTP\u002FHTTPS（通过 HTTP 代理）还是其他 TCP 流量（通过 SOCKS5 代理），都会由这些代理中介，以强制执行您的域名白名单和黑名单。\n\n有关 Claude Code 中沙箱化的更多信息，请参阅：\n\n- [Claude Code 沙箱化文档](https:\u002F\u002Fdocs.claude.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Fsandboxing)\n- [超越权限提示：让 Claude Code 更加安全和自主](https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fclaude-code-sandboxing)\n\n## 架构\n\n```\nsrc\u002F\n├── index.ts                  # 库导出\n├── cli.ts                    # CLI 入口点（srt 命令）\n├── utils\u002F                    # 共享工具\n│   ├── debug.ts             # 调试日志记录\n│   ├── settings.ts          # 设置读取器（权限 + 沙箱配置）\n│   ├── platform.ts          # 平台检测\n│   └── exec.ts              # 命令执行工具\n└── sandbox\u002F                  # 沙箱实现\n    ├── sandbox-manager.ts    # 主沙箱管理器\n    ├── sandbox-schemas.ts    # Zod 模式验证\n    ├── sandbox-violation-store.ts # 违规跟踪\n    ├── sandbox-utils.ts      # 共享沙箱工具\n    ├── http-proxy.ts         # 用于网络过滤的 HTTP\u002FHTTPS 代理\n    ├── socks-proxy.ts        # 用于网络过滤的 SOCKS5 代理\n    ├── linux-sandbox-utils.ts # Linux bubblewrap 沙箱实现\n    └── macos-sandbox-utils.ts # macOS sandbox-exec 沙箱实现\n```\n\n## 使用方法\n\n### 作为命令行工具\n\n`srt` 命令（Anthropic 沙箱运行时）会将任何命令包裹在安全边界内：\n\n```bash\n# 在沙箱中运行命令\nsrt echo \"hello world\"\n\n# 带调试日志\nsrt --debug curl https:\u002F\u002Fexample.com\n\n# 指定自定义设置文件\nsrt --settings \u002Fpath\u002Fto\u002Fsrt-settings.json npm install\n```\n\n### 作为库使用\n\n```typescript\nimport {\n  SandboxManager,\n  type SandboxRuntimeConfig,\n} from '@anthropic-ai\u002Fsandbox-runtime'\nimport { spawn } from 'child_process'\n\n\u002F\u002F 定义你的沙盒配置\nconst config: SandboxRuntimeConfig = {\n  network: {\n    allowedDomains: ['example.com', 'api.github.com'],\n    deniedDomains: [],\n  },\n  filesystem: {\n    denyRead: ['~\u002F.ssh'],\n    allowWrite: ['.', '\u002Ftmp'],\n    denyWrite: ['.env'],\n  },\n}\n\n\u002F\u002F 初始化沙盒（启动代理服务器等）\nawait SandboxManager.initialize(config)\n\n\u002F\u002F 将命令包裹在沙盒限制中\nconst sandboxedCommand = await SandboxManager.wrapWithSandbox(\n  'curl https:\u002F\u002Fexample.com',\n)\n\n\u002F\u002F 执行沙盒化的命令\nconst child = spawn(sandboxedCommand, { shell: true, stdio: 'inherit' })\n\n\u002F\u002F 处理子进程退出并进行清理\nchild.on('exit', async code => {\n  console.log(`命令退出，退出码为 ${code}`)\n  \u002F\u002F 完成后清理（可选，进程退出时会自动清理）\n  await SandboxManager.reset()\n})\n```\n\n#### 可用的导出内容\n\n```typescript\n\u002F\u002F 主沙盒管理器\nexport { SandboxManager } from '@anthropic-ai\u002Fsandbox-runtime'\n\n\u002F\u002F 违规跟踪\nexport { SandboxViolationStore } from '@anthropic-ai\u002Fsandbox-runtime'\n\n\u002F\u002F TypeScript 类型\nexport type {\n  SandboxRuntimeConfig,\n  NetworkConfig,\n  FilesystemConfig,\n  IgnoreViolationsConfig,\n  SandboxAskCallback,\n  FsReadRestrictionConfig,\n  FsWriteRestrictionConfig,\n  NetworkRestrictionConfig,\n} from '@anthropic-ai\u002Fsandbox-runtime'\n```\n\n## 配置\n\n### 设置文件位置\n\n默认情况下，沙盒运行时会在 `~\u002F.srt-settings.json` 中查找配置。你可以使用 `--settings` 标志指定自定义路径：\n\n```bash\nsrt --settings \u002Fpath\u002Fto\u002Fsrt-settings.json \u003Ccommand>\n```\n\n### 完整配置示例\n\n```json\n{\n  \"network\": {\n    \"allowedDomains\": [\n      \"github.com\",\n      \"*.github.com\",\n      \"lfs.github.com\",\n      \"api.github.com\",\n      \"npmjs.org\",\n      \"*.npmjs.org\"\n    ],\n    \"deniedDomains\": [\"malicious.com\"],\n    \"allowUnixSockets\": [\"\u002Fvar\u002Frun\u002Fdocker.sock\"],\n    \"allowLocalBinding\": false\n  },\n  \"filesystem\": {\n    \"denyRead\": [\"~\u002F.ssh\"],\n    \"allowRead\": [],\n    \"allowWrite\": [\".\", \"src\u002F\", \"test\u002F\", \"\u002Ftmp\"],\n    \"denyWrite\": [\".env\", \"config\u002Fproduction.json\"]\n  },\n  \"ignoreViolations\": {\n    \"*\": [\"\u002Fusr\u002Fbin\", \"\u002FSystem\"],\n    \"git push\": [\"\u002Fusr\u002Fbin\u002Fnc\"],\n    \"npm\": [\"\u002Fprivate\u002Ftmp\"]\n  },\n  \"enableWeakerNestedSandbox\": false,\n  \"enableWeakerNetworkIsolation\": false\n}\n```\n\n### 配置选项\n\n#### 网络配置\n\n采用“仅允许模式”——默认情况下所有网络访问均被禁止。\n\n- `network.allowedDomains`：允许访问的域名数组（支持通配符，如 `*.example.com`）。空数组表示无网络访问。\n- `network.deniedDomains`：禁止访问的域名数组（优先级高于 `allowedDomains`）。\n- `network.allowLocalBinding`：是否允许绑定到本地端口（布尔值，默认为 `false`）。\n\n**Unix 套接字设置**（平台相关行为）：\n\n| 设置                        | macOS                     | Linux                                    |\n| ------------------------------ | ------------------------- | ---------------------------------------- |\n| `allowUnixSockets: string[]`   | 允许列表中的套接字路径    | _忽略_（seccomp 无法按路径过滤）        |\n| `allowAllUnixSockets: boolean` | 允许所有套接字            | 禁用 seccomp 阻止                         |\n\nUnix 套接字在两个平台上都默认被阻止。\n\n- **macOS**：使用 `allowUnixSockets` 允许特定路径（如 `[\"\u002Fvar\u002Frun\u002Fdocker.sock\"]`），或设置 `allowAllUnixSockets: true` 来允许所有。\n- **Linux**：阻塞通过 seccomp 过滤器实现（仅适用于 x64 和 arm64 架构）。如果 seccomp 不可用，套接字将不受限制，并显示警告。使用 `allowAllUnixSockets: true` 明确禁用阻塞。\n\n#### 文件系统配置\n\n采用两种不同的模式：\n\n**读取限制**（先拒绝再允许模式）——默认允许所有读取：\n\n- `filesystem.denyRead`：拒绝读取访问的路径数组。空数组表示完全允许读取。\n- `filesystem.allowRead`：在被拒绝区域中重新允许读取的路径数组（优先于 `denyRead`）。**注意**：这与写入限制相反，后者是“先允许再拒绝”的模式。\n\n**写入限制**（仅允许模式）——默认禁止所有写入：\n\n- `filesystem.allowWrite`：允许写入访问的路径数组。空数组表示无写入权限。\n- `filesystem.denyWrite`：在允许写入的路径内进一步拒绝写入的路径数组（优先于 `allowWrite`）。\n\n**路径语法（macOS）：**\n\n在 macOS 上，路径支持类似于 `.gitignore` 的 Git 风格通配符模式：\n\n- `*`：匹配除 `\u002F` 以外的任意字符（如 `*.ts` 匹配 `foo.ts`，但不匹配 `foo\u002Fbar.ts`）。\n- `**`：匹配包括 `\u002F` 在内的任意字符（如 `src\u002F**\u002F*.ts` 匹配 `src\u002F` 目录及其子目录中的所有 `.ts` 文件）。\n- `?`：匹配除 `\u002F` 以外的单个字符（如 `file?.txt` 匹配 `file1.txt`）。\n- `[abc]`：匹配集合中的任意字符（如 `file[0-9].txt` 匹配 `file3.txt`）。\n\n示例：\n\n- `\"allowWrite\": [\"src\u002F\"]`：允许对整个 `src\u002F` 目录进行写入。\n- `\"allowWrite\": [\"src\u002F**\u002F*.ts\"]`：允许对 `src\u002F` 及其子目录中的所有 `.ts` 文件进行写入。\n- `\"denyRead\": [\"~\u002F.ssh\"]`：拒绝访问 SSH 目录。\n- `\"denyRead\": [\"\u002FUsers\"], \"allowRead\": [\".\"]`：拒绝访问 `\u002FUsers` 下的所有目录，但重新允许当前目录。\n- `\"denyWrite\": [\".env\"]`：即使当前目录被允许写入，也禁止对 `.env` 文件进行写入。\n\n**路径语法（Linux）：**\n\n**Linux 目前不支持通配符匹配。** 只能使用精确路径：\n\n- `\"allowWrite\": [\"src\u002F\"]`：允许对 `src\u002F` 目录进行写入。\n- `\"denyRead\": [\"\u002Fhome\u002Fuser\u002F.ssh\"]`：拒绝访问 SSH 目录。\n- `\"denyRead\": [\"\u002Fhome\"], \"allowRead\": [\".\"]`：拒绝访问 `\u002Fhome` 下的所有目录，但重新允许当前目录。\n\n**所有平台：**\n\n- 路径可以是绝对路径（如 `\u002Fhome\u002Fuser\u002F.ssh`）或相对于当前工作目录的路径（如 `.\u002Fsrc`）。\n- `~` 展开为用户的主目录。\n\n#### 其他配置\n\n- `ignoreViolations`：一个对象，将命令模式映射到应忽略违规的路径数组。\n- `enableWeakerNestedSandbox`：为 Docker 环境启用较弱的沙盒模式（布尔值，默认为 `false`）。\n- `enableWeakerNetworkIsolation`：在 macOS 沙盒中允许访问 `com.apple.trustd.agent`（布尔值，默认为 `false`）。这对于 Go 程序（如 `gh`、`gcloud`、`terraform`、`kubectl` 等）在使用 `httpProxyPort` 并配合 MITM 代理和自定义 CA 时验证 TLS 证书是必要的。**安全警告：** 启用此选项可能会通过 trustd 服务导致数据泄露。\n\n### 常见配置示例\n\n**允许访问 GitHub**（所有必要端点）：\n\n```json\n{\n  \"network\": {\n    \"allowedDomains\": [\n      \"github.com\",\n      \"*.github.com\",\n      \"lfs.github.com\",\n      \"api.github.com\"\n    ],\n    \"deniedDomains\": []\n  },\n  \"filesystem\": {\n    \"denyRead\": [],\n    \"allowWrite\": [\".\"],\n    \"denyWrite\": []\n  }\n}\n```\n\n**限制为特定目录：**\n\n```json\n{\n  \"network\": {\n    \"allowedDomains\": [],\n    \"deniedDomains\": []\n  },\n  \"filesystem\": {\n    \"denyRead\": [\"~\u002F.ssh\"],\n    \"allowWrite\": [\".\", \"src\u002F\", \"test\u002F\"],\n    \"denyWrite\": [\".env\", \"secrets\u002F\"]\n  }\n}\n```\n\n**仅限工作区的文件系统访问**（拒绝读取工作区外的内容）：\n\n```json\n{\n  \"network\": {\n    \"allowedDomains\": [],\n    \"deniedDomains\": []\n  },\n  \"filesystem\": {\n    \"denyRead\": [\"\u002FUsers\"],\n    \"allowRead\": [\".\"],\n    \"allowWrite\": [\".\"],\n    \"denyWrite\": []\n  }\n}\n```\n\n此配置会拒绝读取 `\u002FUsers` 目录下的任何内容（在 Linux 上则是 `\u002Fhome`），然后重新允许当前工作目录的读取权限。系统路径（如 `\u002Fusr`、`\u002Flib` 等）仍然可以被读取。\n\n### 常见问题与提示\n\n**运行 Jest：** 使用 `--no-watchman` 标志以避免沙箱违规：\n\n```bash\nsrt \"jest --no-watchman\"\n```\n\nWatchman 会访问沙箱边界之外的文件，从而触发权限错误。禁用 Watchman 后，Jest 将使用内置的文件监视器来运行。\n\n## 平台支持\n\n- **macOS**：使用 `sandbox-exec` 结合自定义配置文件（无需额外依赖）\n- **Linux**：使用 `bubblewrap`（bwrap）进行容器化\n- **Windows**：暂不支持\n\n### 平台特定依赖项\n\n**Linux 需要：**\n\n- `bubblewrap` - 容器运行时\n  - Ubuntu\u002FDebian：`apt-get install bubblewrap`\n  - Fedora：`dnf install bubblewrap`\n  - Arch：`pacman -S bubblewrap`\n- `socat` - 用于代理桥接的套接字中继工具\n  - Ubuntu\u002FDebian：`apt-get install socat`\n  - Fedora：`dnf install socat`\n  - Arch：`pacman -S socat`\n- `ripgrep` - 用于检测禁止路径的快速搜索工具\n  - Ubuntu\u002FDebian：`apt-get install ripgrep`\n  - Fedora：`dnf install ripgrep`\n  - Arch：`pacman -S ripgrep`\n\n**Ubuntu 24.04+ 注意事项：** 这些发行版默认启用了 `kernel.apparmor_restrict_unprivileged_userns`，该设置允许使用 `unshare(CLONE_NEWUSER)`，但会移除新用户命名空间中的能力。而 `bubblewrap` 和 seccomp 隔离层都需要具备能力的用户命名空间。可通过以下命令禁用该限制：\n\n```bash\nsudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0\n```\n\n或者为相关二进制文件添加一个授予 `userns` 能力的 AppArmor 配置文件。\n\n**可选的 Linux 依赖项（用于 seccomp 备用方案）：**\n\n该软件包包含针对 x86-64 和 arm 架构预生成的 seccomp BPF 过滤器。这些依赖项仅在您使用的架构没有预生成过滤器时才需要：\n\n- `gcc` 或 `clang` - C 编译器\n- `libseccomp-dev` - Seccomp 库开发文件\n  - Ubuntu\u002FDebian：`apt-get install gcc libseccomp-dev`\n  - Fedora：`dnf install gcc libseccomp-devel`\n  - Arch：`pacman -S gcc libseccomp`\n\n**macOS 需要：**\n\n- `ripgrep` - 用于检测禁止路径的快速搜索工具\n  - 可通过 Homebrew 安装：`brew install ripgrep`\n  - 或从以下网址下载：https:\u002F\u002Fgithub.com\u002FBurntSushi\u002Fripgrep\u002Freleases\n\n## 开发\n\n```bash\n# 安装依赖\nnpm install\n\n# 构建项目\nnpm run build\n\n# 运行测试\nnpm test\n\n# 类型检查\nnpm run typecheck\n\n# 代码格式化\nnpm run lint\n\n# 代码格式化\nnpm run format\n```\n\n### 构建 Seccomp 二进制文件\n\nBPF 过滤器和 `apply-seccomp` 加载程序是从 `vendor\u002Fseccomp-src\u002F` 中的 C 源代码编译而来，通过 `npm run build:seccomp` 命令完成（仅限 Linux；需要 `gcc` 和 `libseccomp-dev`）。CI 会在每次 Linux 架构的测试前运行此命令，发布流程则会构建两种架构的版本，并将其打包到发布的软件包中。\n\n## 实现细节\n\n### 网络隔离架构\n\n沙箱在宿主机上运行 HTTP 和 SOCKS5 代理服务器，根据权限规则过滤所有网络请求：\n\n1. **HTTP\u002FHTTPS 流量**：HTTP 代理服务器拦截请求，并根据允许\u002F禁止的域名对其进行验证。\n2. **其他网络流量**：SOCKS5 代理处理所有其他 TCP 连接（SSH、数据库连接等）。\n3. **权限执行**：代理会强制执行您配置中的 `permissions` 规则。\n\n**平台特定的代理通信方式：**\n\n- **Linux**：请求通过文件系统经由 Unix 域套接字路由（使用 `socat` 进行桥接）。bubblewrap 容器中会移除网络命名空间，确保所有网络流量必须经过代理。\n- **macOS**：Seatbelt 配置文件仅允许与代理监听的特定本地回环端口通信。其他所有网络访问均被阻止。\n\n### 文件系统隔离\n\n文件系统限制在操作系统级别强制执行：\n\n- **macOS**：使用 `sandbox-exec` 结合动态生成的 Seatbelt 配置文件，指定允许的读写路径。\n- **Linux**：使用 `bubblewrap` 结合绑定挂载，根据配置将目录标记为只读或读写。\n\n**默认文件系统权限：**\n\n- **读取**（先禁止再允许）：默认情况下处处允许。您可以先禁止大范围区域，然后再重新允许其中的特定路径。`allowRead` 的优先级高于 `denyRead`。\n\n  - 示例：`denyRead: [\"~\u002F.ssh\"]` 以阻止访问 SSH 密钥。\n  - 示例：`denyRead: [\"\u002FUsers\"], allowRead: [\".\"]` 以阻止访问整个 `\u002FUsers` 目录，仅保留工作区的访问权限。\n  - 如果 `denyRead: []`，则表示完全开放读取权限（无任何禁止）。\n\n- **写入**（仅允许）：默认情况下处处禁止。您必须显式地允许某些路径。\n\n  - 示例：`allowWrite: [\".\", \"\u002Ftmp\"]` 允许向当前目录和 \u002Ftmp 写入。\n  - 如果 `allowWrite: []`，则表示完全禁止写入（无任何允许）。\n  - `denyWrite` 则是在允许的路径内创建例外情况（禁止优先于允许）。\n\n**读取与写入的优先级恰好相反：** `allowRead` 会覆盖 `denyRead`，而 `denyWrite` 则会覆盖 `allowWrite`。这样您就可以在被禁止的区域内划出可读取的区域，同时在可写入的区域内划定受保护的区域。\n\n### 强制拒绝路径（自动保护的文件）\n\n某些敏感文件和目录**始终禁止写入**，即使它们位于允许写入的路径范围内。这为防范沙箱逃逸和配置篡改提供了纵深防御。\n\n**始终阻止的文件：**\n\n- Shell 配置文件：`.bashrc`、`.bash_profile`、`.zshrc`、`.zprofile`、`.profile`\n- Git 配置文件：`.gitconfig`、`.gitmodules`\n- 其他敏感文件：`.ripgreprc`、`.mcp.json`\n\n**始终阻止的目录：**\n\n- IDE 目录：`.vscode\u002F`、`.idea\u002F`\n- Claude 配置目录：`.claude\u002Fcommands\u002F`、`.claude\u002Fagents\u002F`\n- Git 钩子与配置：`.git\u002Fhooks\u002F`、`.git\u002Fconfig`\n\n这些路径会自动被阻止——您无需将其添加到 `denyWrite` 中。例如，即使设置了 `allowWrite: [\".\"]`，尝试写入 `.bashrc` 或 `.git\u002Fhooks\u002Fpre-commit` 仍会失败：\n\n```bash\n$ srt 'echo \"malicious\" >> .bashrc'\n\u002Fbin\u002Fbash: .bashrc: 操作不允许\n\n$ srt 'echo \"bad\" > .git\u002Fhooks\u002Fpre-commit'\n\u002Fbin\u002Fbash: .git\u002Fhooks\u002Fpre-commit: 操作不允许\n```\n\n**注意（Linux）：** 在 Linux 上，强制拒绝路径仅会阻止已存在的文件。对于这些模式下的不存在文件，bubblewrap 的绑定挂载方式无法进行拦截。而 macOS 使用 glob 模式匹配，能够同时阻止现有文件和新创建的文件。\n\n**Linux 搜索深度：** 在 Linux 上，沙箱会使用 `ripgrep` 扫描允许写入路径中的子目录，查找危险文件。默认情况下，为了性能考虑，它最多搜索 3 层深度。您可以通过设置 `mandatoryDenySearchDepth` 来调整此值：\n\n```json\n{\n  \"mandatoryDenySearchDepth\": 5,\n  \"filesystem\": {\n    \"allowWrite\": [\".\"]\n  }\n}\n```\n\n- 默认值：`3`（搜索最多 3 层）\n- 范围：`1` 至 `10`\n- 值越高，防护越全面，但性能会有所下降\n- 当前工作目录（深度 0）中的文件无论此设置如何都会受到保护。\n\n### Unix 套接字限制（Linux）\n\n在 Linux 上，沙箱利用 **seccomp BPF（伯克利数据包过滤器）** 在系统调用层面阻止 Unix 域套接字的创建。这一机制提供了一层额外的安全保障，防止进程通过本地 IPC 创建新的 Unix 域套接字（除非明确允许）。\n\n**工作原理：**\n\n1. **内置 BPF 过滤器**：该软件包为 x64 和 arm64 架构分别提供了静态编译的 `apply-seccomp` 二进制文件，其中已嵌入 seccomp BPF 过滤器。该过滤器针对特定架构设计，但独立于 libc，因此无论使用 glibc 还是 musl，该二进制文件均可正常运行。\n   \n2. **运行时检测**：沙箱会自动检测您的系统架构，并选择对应的 `apply-seccomp` 二进制文件。\n\n3. **系统调用过滤**：BPF 过滤器会拦截 `socket()` 系统调用，通过返回 `EPERM` 错误来阻止 `AF_UNIX` 套接字的创建。这样可以防止沙箱内的代码创建新的 Unix 域套接字。\n\n4. **使用 apply-seccomp 二进制文件的两阶段应用：**\n   - 外层 bwrap 创建包含文件系统、网络和 PID 命名空间限制的沙箱。\n   - 网络桥接进程（socat）会在沙箱内部启动（需要 Unix 域套接字）。\n   - apply-seccomp 会创建一个嵌套的 user+PID+mount 命名空间，并重新挂载 `\u002Fproc`。\n   - 在嵌套命名空间内，apply-seccomp 作为 PID 1（不可转储的 init\u002Freaper）运行。\n   - apply-seccomp 会 fork 子进程，通过 `prctl()` 应用 seccomp 过滤器，然后 exec 用户命令。\n   - 用户命令将在所有沙箱限制的基础上，额外受到 Unix 域套接字创建的阻断。\n\n**PID 命名空间隔离：** 嵌套的 PID 命名空间确保用户命令无法看到或访问任何未应用 seccomp 过滤器的进程（bwrap 的 init、shell 包装器或 socat 辅助进程）。这样一来，无论 `kernel.yama.ptrace_scope` 设置为何，seccomp 边界都能保持完整，因为未经过滤的辅助进程无法通过 `ptrace` 或 `\u002Fproc\u002FN\u002Fmem` 访问。内部的 PID 1 会将 `PR_SET_DUMPABLE=0`，使其同样无法被 ptrace。如果嵌套命名空间创建失败，apply-seccomp 将直接终止，而不是在缺乏隔离的情况下继续运行。\n\n**安全限制：** 该过滤器会阻止 `socket(AF_UNIX, ...)` 以及 `io_uring_setup`、`io_uring_enter` 和 `io_uring_register` 系统调用（后三者是因为在 Linux 5.19 及以上版本中，`IORING_OP_SOCKET` 会绕过 `socket()` 规则）。但它无法阻止对从父进程继承或通过 `SCM_RIGHTS` 传递的 Unix 域套接字文件描述符的操作。对于大多数沙箱场景而言，阻止套接字创建足以防止未经授权的 IPC。\n\n**零运行时依赖：** 预编译的静态 apply-seccomp 二进制文件及预生成的 BPF 过滤器已分别针对 x64 和 arm64 架构打包提供，运行时无需任何编译工具或外部依赖。\n\n**架构支持：** 目前完全支持 x64 和 arm64 架构，其他架构暂不支持。若要在不支持的架构上使用沙箱功能但不禁用 Unix 域套接字，请在配置中设置 `allowAllUnixSockets: true`。\n\n### 违规检测与监控\n\n当沙箱进程尝试访问受限制的资源时：\n\n1. **在操作系统层面阻止该操作**（返回 `EPERM` 错误）\n2. **记录违规日志**（平台特定机制）\n3. **通知用户**（在 Claude Code 中，这会触发权限提示）。\n\n**macOS：** 沙箱运行时会接入 macOS 的系统沙箱违规日志存储。这可提供实时通知，详细说明尝试了什么操作以及为何被阻止。这也是 Claude Code 用于违规检测的相同机制。\n\n```bash\n# 实时查看沙箱违规\nlog stream --predicate 'process == \"sandbox-exec\"' --style syslog\n```\n\n**Linux：** Bubblewrap 并不提供内置的违规报告功能。您可以使用 `strace` 来跟踪系统调用并识别被阻止的操作：\n\n```bash\n# 跟踪所有被拒绝的操作\nstrace -f srt \u003Cyour-command> 2>&1 | grep EPERM\n\n# 跟踪特定文件操作\nstrace -f -e trace=open,openat,stat,access srt \u003Cyour-command> 2>&1 | grep EPERM\n\n# 跟踪网络操作\nstrace -f -e trace=network srt \u003Cyour-command> 2>&1 | grep EPERM\n```\n\n### 高级：自定义代理\n\n对于更复杂的网络过滤需求，您可以配置沙箱使用自己的代理服务器，而非内置代理。这样可以实现：\n\n- **流量检查**：使用如 [mitmproxy](https:\u002F\u002Fmitmproxy.org\u002F) 等工具检查和修改流量。\n- **自定义过滤逻辑**：实施超越简单域名白名单的复杂规则。\n- **审计日志记录**：记录所有网络请求以满足合规性或调试需求。\n\n**使用 mitmproxy 的示例：**\n\n```bash\n# 启动带有自定义过滤脚本的 mitmproxy\nmitmproxy -s custom_filter.py --listen-port 8888\n```\n\n注意：自定义代理配置尚未在新配置格式中支持。此功能将在未来的版本中加入。\n\n**重要的安全考量：** 即使启用了域名白名单，仍可能存在信息泄露途径。例如，允许访问 `github.com` 就会让进程向任意仓库推送内容。通过自定义 MITM 代理并正确配置证书，您可以检查和过滤特定的 API 调用，从而避免此类风险。\n\n### 安全限制\n\n- 网络沙箱限制：网络过滤系统通过限制进程允许连接的域名来工作。它不会对通过代理传输的流量进行其他检查，因此用户有责任确保其策略中仅允许受信任的域名。\n\n\u003C警告>\n用户应注意，允许诸如 `github.com` 等广泛域名可能带来的风险，因为这可能导致数据外泄。此外，在某些情况下，攻击者可能通过 [域名伪装](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FDomain_fronting) 来绕过网络过滤。\n\u003C\u002F警告>\n\n- 通过 Unix 套接字提升权限：`allowUnixSockets` 配置可能会无意中授予对强大系统服务的访问权限，从而导致沙箱被绕过。例如，如果该配置用于允许访问 `\u002Fvar\u002Frun\u002Fdocker.sock`，则可通过利用 Docker 套接字有效地获得对宿主机系统的访问权限。建议用户谨慎考虑允许通过沙箱访问的任何 Unix 套接字。\n- 文件系统权限提升：过于宽泛的文件系统写入权限可能引发权限提升攻击。允许向 `$PATH` 中包含可执行文件的目录、系统配置目录或用户 shell 配置文件（如 `.bashrc`、`.zshrc`）写入内容，当其他用户或系统进程访问这些文件时，可能导致在不同安全上下文中执行代码。\n- Linux 沙箱强度：Linux 实现提供了强大的文件系统和网络隔离，但包含一个 `enableWeakerNestedSandbox` 模式，使其能够在不使用特权命名空间的 Docker 环境中运行。此选项会显著削弱安全性，应仅在已通过其他方式强制实施额外隔离的情况下使用。\n- 较弱的网络隔离（macOS）：`enableWeakerNetworkIsolation` 选项会重新启用对 `com.apple.trustd.agent` 的访问权限，而该服务是 Go 程序通过 macOS 安全框架验证 TLS 证书所必需的。这将打开一条通过 trustd 服务进行数据外泄的潜在途径，因此仅应在需要 Go TLS 验证时才启用此选项（例如，使用 `httpProxyPort` 并配合 MITM 代理及自定义 CA 时）。\n\n### 已知限制与未来工作\n\n**Linux 代理绕过**：目前使用环境变量（`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`）将流量导向代理。这对大多数应用程序有效，但某些不尊重这些环境变量的程序可能会忽略它们，从而无法连接到互联网。\n\n**未来改进方向：**\n\n- **Proxychains 支持**：在 Linux 上添加对 `proxychains` 和 `LD_PRELOAD` 的支持，以便在更低级别拦截网络调用，从而增加绕过难度。\n- **Linux 违规监控**：为 Linux 实现基于 `strace` 的自动违规检测功能，并将其与违规存储集成。目前，Linux 用户必须手动运行 `strace` 才能查看违规情况，而 macOS 则可通过系统日志存储实现自动违规监控。","# Anthropic Sandbox Runtime (srt) 快速上手指南\n\nAnthropic Sandbox Runtime (`srt`) 是一个轻量级的沙箱工具，旨在操作系统层面为任意进程强制执行文件系统和网络限制，且无需依赖容器技术。它专为提升 AI Agent、本地 MCP 服务器及命令行工具的安全性而设计，遵循“默认安全”原则。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **操作系统**：\n    *   **macOS**：原生支持（基于 `sandbox-exec`）。\n    *   **Linux**：需要安装 `bubblewrap` 用于容器化隔离。\n        *   Debian\u002FUbuntu: `sudo apt install bubblewrap`\n        *   Fedora\u002FRHEL: `sudo dnf install bubblewrap`\n        *   Arch Linux: `sudo pacman -S bubblewrap`\n*   **运行时环境**：已安装 **Node.js** (推荐 v18+) 和 **npm**。\n*   **网络环境**：由于该包发布在 npm 官方源，国内用户建议配置淘宝镜像源以加速安装。\n\n## 安装步骤\n\n### 1. 配置国内镜像源（推荐）\n为避免下载缓慢或失败，建议临时或永久切换至国内镜像源：\n\n```bash\n# 临时使用淘宝镜像安装\nnpm install -g @anthropic-ai\u002Fsandbox-runtime --registry=https:\u002F\u002Fregistry.npmmirror.com\n\n# 或者永久设置镜像源\nnpm config set registry https:\u002F\u002Fregistry.npmmirror.com\n```\n\n### 2. 全局安装\n执行以下命令全局安装 `srt`：\n\n```bash\nnpm install -g @anthropic-ai\u002Fsandbox-runtime\n```\n\n安装完成后，即可在终端直接使用 `srt` 命令。\n\n## 基本使用\n\n`srt` 的使用非常简单，只需在原有命令前加上 `srt` 即可。默认情况下，它会阻止所有网络访问（除非显式允许）并限制敏感文件的写入。\n\n### 1. 测试网络限制\n默认策略下，未在白名单中的域名将被拦截。\n\n```bash\n# 尝试访问未被允许的域名（将被拦截）\n$ srt \"curl example.com\"\nRunning: curl example.com\nConnection blocked by network allowlist  # 请求被阻断\n\n# 注意：若要允许特定域名，需创建 ~\u002F.srt-settings.json 配置文件\n```\n\n### 2. 测试文件系统限制\n默认允许读取当前目录，但禁止读取敏感系统文件（如 SSH 密钥）或写入未授权路径。\n\n```bash\n# 读取当前目录文件（允许）\n$ srt \"cat README.md\"\nRunning: cat README.md\n# Anthropic Sandb... \n\n# 读取敏感文件（被拦截）\n$ srt \"cat ~\u002F.ssh\u002Fid_rsa\"\nRunning: cat ~\u002F.ssh\u002Fid_rsa\ncat: \u002FUsers\u002Follie\u002F.ssh\u002Fid_rsa: Operation not permitted  # 操作被禁止\n```\n\n### 3. 进阶：配合 MCP Server 使用\n这是 `srt` 的核心场景之一。通过修改 `.mcp.json`，将 `command` 替换为 `srt`，即可为 MCP 服务加上安全锁。\n\n**修改前：**\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\"]\n    }\n  }\n}\n```\n\n**修改后（启用沙箱）：**\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"srt\",\n      \"args\": [\"npx\", \"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\"]\n    }\n  }\n}\n```\n\n> **提示**：生产环境中，请务必在用户主目录下创建 `~\u002F.srt-settings.json` 文件，明确配置 `allowedDomains`（允许的网络域名）和 `allowWrite`（允许写入的路径），否则服务可能因权限不足无法正常工作。","某开发团队在本地部署 AI 助手时，需要让模型调用文件系统工具（MCP Server）来整理项目文档，但极度担心模型因“幻觉”误删核心代码或泄露 SSH 密钥。\n\n### 没有 sandbox-runtime 时\n- **权限过大风险**：AI 进程以当前用户全权限运行，一旦生成错误指令（如 `rm -rf`），可直接删除整个主目录下的敏感文件。\n- **数据泄露隐患**：模型若被诱导执行恶意命令，可随意读取 `~\u002F.ssh\u002Fid_rsa` 等隐私凭证并外传，毫无阻拦。\n- **网络不可控**：进程可能擅自连接外部未知域名，导致内部代码库被偷偷上传至攻击者服务器。\n- **防御成本高昂**：若要限制权限，通常需配置复杂的 Docker 容器或虚拟机，增加了本地开发的资源消耗和维护难度。\n- **缺乏实时反馈**：当违规操作发生时，系统仅静默失败或直接崩溃，开发者难以定位是 AI 行为异常还是环境配置错误。\n\n### 使用 sandbox-runtime 后\n- **最小权限原则**：通过配置文件明确只允许 AI 读写当前项目目录，尝试访问 `~\u002Fsensitive-folder` 时直接报错“操作不被允许”。\n- **精准文件隔离**：利用操作系统原生原语（如 macOS 的 sandbox-exec），从内核层阻断对 SSH 密钥等特定文件的读取请求。\n- **网络白名单机制**：默认禁止所有网络连接，仅放行必要的官方 API 域名，彻底切断数据外泄通道。\n- **轻量无感集成**：无需启动沉重的容器，只需在 MCP 配置中将命令包裹在 `srt` 内，即可实现秒级沙箱化。\n- **违规透明监控**：当 AI 试图越界时，系统会实时拦截并返回清晰的错误日志，帮助开发者快速修正提示词或策略。\n\nsandbox-runtime 通过操作系统级的轻量隔离，让本地 AI 代理在享受文件操作便利的同时，默认拥有“防弹”般的安全边界。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fanthropic-experimental_sandbox-runtime_67d83c6c.png","anthropic-experimental","Anthropic-experimental","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fanthropic-experimental_ba1e38c8.png","",null,"https:\u002F\u002Fanthropic.com","https:\u002F\u002Fgithub.com\u002Fanthropic-experimental",[81,85],{"name":82,"color":83,"percentage":84},"TypeScript","#3178c6",97.8,{"name":86,"color":87,"percentage":88},"JavaScript","#f1e05a",2.2,3811,261,"2026-04-17T18:09:16","Apache-2.0","Linux, macOS","未说明",{"notes":96,"python":94,"dependencies":97},"该工具是一个基于 Node.js 的沙箱运行时，无需容器即可在操作系统级别限制进程的文件系统和网络访问。Linux 端依赖 bubblewrap 进行隔离，macOS 端使用原生的 sandbox-exec (Seatbelt profiles)。网络过滤通过代理服务器（HTTP\u002FSOCKS5）实现。默认配置下网络访问被完全禁止，需显式配置允许的域名；写操作默认禁止，需显式允许路径。",[98,99,100],"bubblewrap (Linux)","sandbox-exec (macOS 原生)","Node.js\u002Fnpm",[13,45],"2026-03-27T02:49:30.150509","2026-04-18T09:19:29.216016",[],[106,111,116,121,126,131,136,141,146,151,156,161],{"id":107,"version":108,"summary_zh":109,"released_at":110},315396,"v0.0.49","## 变更内容\n* 由 @dylan-conway 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F206 中移除了 lodash-es 依赖项\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fcompare\u002Fv0.0.48...v0.0.49","2026-04-03T02:00:51",{"id":112,"version":113,"summary_zh":114,"released_at":115},315397,"v0.0.48","## 变更内容\n* 升级至 0.0.48 版本，并由 @dylan-conway 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F205 中修复了 npm audit 漏洞。\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fcompare\u002Fv0.0.47...v0.0.48","2026-04-03T01:40:44",{"id":117,"version":118,"summary_zh":119,"released_at":120},315398,"v0.0.47","## 变更内容\n* 在 CI 中运行完整的测试套件，并将平台跳过项迁移到 `describe.if`，由 @dylan-conway 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F197 中完成\n* 修复在 `deny` 策略下允许读取的顺序问题，由 @carderne 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F170 中完成\n* 测试：验证在 `denyRead` 父级策略下 `allowWrite` 中的 `rm` 操作（针对 #170 的后续改进），由 @poteat 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F198 中完成\n* 将 BPF 过滤器烘焙进 `apply-seccomp`，并在 CI 中构建，由 @dylan-conway 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F199 中完成\n* 添加用于多调用二进制文件调用的 seccomp `argv0` 模式，由 @dylan-conway 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F203 中完成\n* 添加 `allowMachLookup` 配置，以支持额外的 macOS XPC 服务，由 @dylan-conway 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F204 中完成\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fcompare\u002Fv0.0.46...v0.0.47","2026-04-02T21:36:05",{"id":122,"version":123,"summary_zh":124,"released_at":125},315399,"v0.0.46","## 变更内容\n* 修复在应用 seccomp 命名空间更改后 `enableWeakerNestedSandbox` 的问题，由 @dylan-conway 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F196 中完成。\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fcompare\u002Fv0.0.45...v0.0.46","2026-03-31T19:56:54",{"id":127,"version":128,"summary_zh":129,"released_at":130},315400,"v0.0.45","包括 #184（推迟并行沙盒的 bwrap 挂载清理）、#190（禁止读取根目录的隔离区域 + 禁止写入的去重）以及 #195（修复 denyWrite 解掩码回归问题 + 实现迭代顺序无关性）。","2026-03-31T18:30:53",{"id":132,"version":133,"summary_zh":134,"released_at":135},315401,"v0.0.44","包括 #190（拒绝读取 “\u002F” 的例外 + 拒绝写入去重）和 #187（上游 HTTP 代理支持）。","2026-03-30T23:14:54",{"id":137,"version":138,"summary_zh":139,"released_at":140},315402,"v0.0.43","## 变更内容\n* 沙箱加固：TMPDIR 写入范围及 seccomp 参数比较，由 @ddworken 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F182 中实现\n* 为沙箱添加上游\u002F父级 HTTP 代理支持，由 @MarshallOfSound 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F187 中实现\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fcompare\u002Fv0.0.42...v0.0.43","2026-03-28T03:29:15",{"id":142,"version":143,"summary_zh":144,"released_at":145},315403,"v0.0.42","## 变更内容\n* 功能：新增 `allowRead` 配置选项，其优先级高于 `denyRead`，由 @carderne 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F166 中实现。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fcompare\u002Fv0.0.41...v0.0.42","2026-03-12T23:12:26",{"id":147,"version":148,"summary_zh":149,"released_at":150},315404,"v0.0.41","## 变更内容\n* 修复：在 Linux 上设置 `GIT_SSH_COMMAND`，使通过 SSH 使用的 Git 能够通过代理解析 DNS，由 @ddworken 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F168 中完成。\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fcompare\u002Fv0.0.40...v0.0.41","2026-03-12T18:44:44",{"id":152,"version":153,"summary_zh":154,"released_at":155},315405,"v0.0.40","## 变更内容\n* 功能：在 RipgrepConfig 中支持 argv0，由 @dylan-conway 在 https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F163 中实现。\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fcompare\u002Fv0.0.39...v0.0.40","2026-03-09T18:51:01",{"id":157,"version":158,"summary_zh":159,"released_at":160},315406,"v0.0.39","Bump patch version to 0.0.39","2026-02-26T03:16:52",{"id":162,"version":163,"summary_zh":164,"released_at":165},315407,"v0.0.38","## What's Changed\r\n* fix: use wildcard in allowLocalBinding seatbelt rules for IPv6 dual-stack compatibility by @dylan-conway in https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F127\r\n* security: warn and skip symlink write paths pointing outside boundaries by @ddworken in https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F138\r\n* fix: allow Unix domain socket creation in network-restricted sandbox by @thomasballinger in https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F140\r\n* ci: add npm release workflow by @dylan-conway in https:\u002F\u002Fgithub.com\u002Fanthropic-experimental\u002Fsandbox-runtime\u002Fpull\u002F143","2026-02-19T22:55:37"]