Aegis

Claude Code 的沙箱默认允许 agent 读取你的 SSH 密钥和 AWS 凭据。Aegis 不会。

两层防护，均已在真实硬件上验证。

内核沙箱——agent 自身的 shell 无法访问被拒绝的路径：

$ ! cat ~/.ssh/id_rsa
cat: /Users/you/.ssh/id_rsa: Operation not permitted

$ ! cat ~/.aws/credentials
cat: /Users/you/.aws/credentials: Operation not permitted

$ tail ~/Library/Application\ Support/Aegis/denials.log
kernel denied file-read-data /Users/you/.ssh/id_rsa to cat(pid 41560)
kernel denied file-read-data /Users/you/.aws/credentials to cat(pid 42180)

MCP 代理——同一工具、同一文件，分别在有无 Aegis 前置的情况下：

direct to the server:   allowed: TOKEN=proof-env-secret
through aegis proxy:    AEGIS DENIED: read_text_file
                        Reason: path matches deny rule '.env'
                        Rule: deny_paths

0.9.0 中的新内容

每一行都有针对此版本运行的测试作为支撑；对于尚未测试的内容，会明确说明。

• aegis workspace add / remove / list — 无需编辑 policy.json 即可更改智能体可工作的文件夹。添加操作始终需要 --confirm-grant；移除操作则不需要。add 会拒绝你的主目录、任何包含 Aegis 自身文件的目录、包含 .. 的路径、不存在的文件夹、位于工作区内的符号链接，以及位于另一个工作区内部或周围的工作区。每次更改都会记录在审计日志中，并重新生成沙箱配置文件。已经运行的会话会保留其启动时的工作区——包括你刚刚移除的那个——这是针对一个正在运行的沙箱会话实测得出的。
• 两条扩大访问权限的途径已被封堵。 在 0.8.1 中，植入工作区内的符号链接可以通过 aegis policy set-folder 被变成新的工作区，从而授予链接指向的任何位置的权限；而在另一个工作区内创建的工作区，之后可能被替换为符号链接，并在下次启动时被跟随。两者均已在 0.8.1 上复现，现已成为永久回归测试，并已证明在该版本上会失败。
• policy.json 中的相对路径会被拒绝。 相对路径是相对于 Aegis 启动时所在的文件夹解析的，因此 aegis run 和启动包装器可能从同一策略强制执行不同的沙箱（实测：不同的配置文件摘要）。路径必须是绝对路径或以 ~/ 开头。
• 每次策略更改都会重新生成沙箱配置文件，因此 aegis doctor 不再报告编辑与下次启动之间的不匹配。
• 当 Claude Code 无法在沙箱内登录时的一种解决办法。 aegis run 和 aegis doctor 会打印真实的 Claude Code 路径——从 Aegis 写入的包装器中读取——以及 /login，以便在沙箱外运行。未修复：被撤销或过期的令牌在第一条消息失败之前仍会显示为已登录（Claude Code 的状态报告不包含过期信息），并且登录仍然无法在沙箱内进行；这需要一个尚不存在的凭据代理。
• aegis init 保护尚未登录的新用户。 通过在干净环境中按照演练步骤操作发现：在 0.8.1 中，从未登录过的 Claude Code 默认未被包装，隐藏在一个文档从未提及的问题之后，因此 claude 停留在沙箱之外。现在，一旦你同意启用沙箱，它就会被包装，并伴有醒目的警告，要求你在沙箱外登录一次（使用真实的 Claude Code 路径，然后执行 /login）；aegis init 的收尾步骤将此放在首位，在你完成之前 aegis doctor 会失败。同一次运行还修复了 init 的开头和结尾文本，为 aegis init、aegis run 和 aegis doctor 提供了统一的登录说明，并阻止了无操作更改打印 nothing to change (nothing to change)。
• 文件夹权限说明了它们实际触及的范围。 Ask 仅适用于 MCP 工具调用；Claude Code 自身的文件工具和 shell 由沙箱决定，沙箱将读取和写入分开处理——实测结果见 docs/getting-started.md 中的表格。Deny 现在会同时阻止读取和写入，包括对不在任何工作区中的文件夹，并拒绝包含 Aegis 自身文件的文件夹。
• 测试框架： 防止测试运行影响你真实安装的防护机制，在沙箱会话运行时不再随机失败。它会将该会话的检查点行归因，并仍然报告其他任何情况。（测试代码，不属于软件包的一部分。）

0.9.0 中尚未测试：Linux；Claude Code 以外的客户端；/login 流程的端到端测试；重建的桌面应用。

功能说明

位于你的 AI 编码智能体与你的机器之间：

• 默认拒绝所有工具调用
• 内核沙箱作用于子进程——cat .env 无法绕过它
• 防篡改审计日志——哈希链式，由 aegis doctor 进行完整性检查，并从沙箱外部在沙箱无法读取或写入的密钥下进行检查点记录
• 出站请求在发出前经过检查
• 机密永远不会到达 MCP 服务器

安装（macOS Apple Silicon）

初次使用？docs/getting-started.md 是分步指南，包括两个默认为“否”的问题。

之前按照说明安装了 aegis-mcp？ 那个包不是 Aegis——它是一个无关的项目，却安装在同一个导入名 aegis 下。请先卸载它：

python3 -m pip uninstall aegis-mcp

如果已经安装了 aegis-sandbox，该卸载操作也会删除它的两个文件，因此之后需要重新安装：python3 -m pip install --force-reinstall aegis-sandbox。

python3 -m pip install aegis-sandbox
aegis init      # 检测 Claude Code / Cursor，询问几个问题
aegis doctor    # 验证边界确实已就位

要升级？ 重新运行 aegis init。你的 policy.json 属于你自己，绝不会在背后被重写，因此新的沙箱域名不会自动出现——而且如果没有 OAuth token 端点，沙箱客户端在 token 过期后就会停止工作。aegis init 会提供新的主机；接受只需按一次键。

它不做什么

• 不能阻止提示注入
• 内核逃逸会攻破沙箱
• 审计数据库在沙箱内部仍然可写。检查点使篡改已被检查点记录的历史可被检测——但并非不可能，而且最新的行尚未被覆盖
• 沙箱客户端完全无法登录。请在 aegis init 之前登录 Claude Code；如果被包装的客户端未登录，aegis doctor 会失败
• 沙箱客户端无法续期已过期的登录 token——请在沙箱外运行一次以刷新
• 沙箱仍然可以从 Keychain 读取你的 OAuth token
• 大于 16 MiB 的工具结果会被拒绝
• 没有外部安全审查，没有认证
• 除我之外无人审计——完整源代码作为 sdist 发布在 PyPI 上；请阅读它，这就是它采用 MIT 的原因

完整威胁模型：THREAT-MODEL.md

许可证

MIT