Agent Safehouse

为 macOS 上的 AI 编程 Agent 提供沙盒环境，确保它们仅能访问所需的特定文件和集成服务。

Agent Safehouse 使用带有可组合策略配置文件的 sandbox-exec 以及“默认拒绝”模型。它内置了针对主流编程 Agent 和应用托管 Agent 工作流的配置文件，同时保证正常的开发工作流程不受影响。

安装

Homebrew:

brew install eugene1g/safehouse/agent-safehouse

独立脚本:

mkdir -p ~/.local/bin
curl -fsSL https://github.com/eugene1g/agent-safehouse/releases/latest/download/safehouse.sh \
  -o ~/.local/bin/safehouse
chmod +x ~/.local/bin/safehouse

设计理念

Agent Safehouse 的核心在于实用的最小权限原则：

• 从“全部拒绝”开始。
• 仅允许 Agent 完成任务所必需的访问权限。
• 保持开发工作流的高效性。
• 默认降低风险，操作简单。

这仅仅是一个加固层，而非针对蓄意攻击者的完美安全边界。

默认 HOME 访问权限

HOME_DIR 用于在生成的策略中渲染精确的相对路径规则。它本身并不会授予对你主目录的递归读取权限。

Safehouse 的默认行为更加严苛：

• 仅对 /、$HOME 路径以及 $HOME 本身进行元数据遍历，以便运行时能够探测已明确允许的目录。
• 对 ~/.config 和 ~/.cache 进行目录根目录读取，以便工具可以发现 XDG 配置位置。
• 常驻配置文件中包含少量显式的主目录文件/目录，例如 git/ssh 元数据和共享的 Agent 指令文件夹。

在实践中，stat "$HOME" 可以成功执行，但 ls "$HOME" 和 cat ~/secret.txt 仍然会失败，除非有更具体的规则授予该路径访问权限。

如果你想移除默认的主目录例外，请使用 --append-profile；附加的配置文件会最后加载，因此其中的拒绝规则可以覆盖并细化之前的默认设置。

内置系统路径解析

Safehouse 的内置 profiles/* 模块可能包含 macOS 兼容路径，例如 /etc、/private/etc/resolv.conf 或 /private/etc/localtime。

在策略渲染时，Safehouse 会从 allow file-read* 规则中解析内置的绝对路径，并在作者定义的路径为软链接时，为实际目标路径生成匹配的授权。这使得主机特定的系统文件能够正常工作，而无需将源配置文件扩展为对 /private/etc 的递归访问。

目前的范围仅限于内置的 literal（字面量）和 subpath（子路径）读取授权。用户提供的路径授权会单独进行规范化，而可写或仅限元数据的内置规则目前尚不支持自动扩展。

文档

• 官网: agent-safehouse.dev
• 文档: agent-safehouse.dev/docs
• 策略生成器: agent-safehouse.dev/policy-builder

机器特定的默认设置

如果你在特定于机器的位置存放共享代码库、缓存或团队文件夹，请将这些设置排除在项目配置之外，改为放入 shell 包装器和本地附加配置文件中。

这样你就可以一次性定义好合理的默认值，并在 claude、codex、amp 或其他应用启动器中复用：

POSIX shells (zsh / bash):

# ~/.zshrc or ~/.bashrc
export SAFEHOUSE_APPEND_PROFILE="$HOME/.config/agent-safehouse/local-overrides.sb"

safe() {
  safehouse \
    --add-dirs-ro="$HOME/server" \
    --append-profile="$SAFEHOUSE_APPEND_PROFILE" \
    "$@"
}

safe-claude() { safe claude --dangerously-skip-permissions "$@" }

fish:

# ~/.config/fish/config.fish
set -gx SAFEHOUSE_APPEND_PROFILE "$HOME/.config/agent-safehouse/local-overrides.sb"

function safe
    safehouse \
      --add-dirs-ro="$HOME/server" \
      --append-profile="$SAFEHOUSE_APPEND_PROFILE" \
      $argv
end

function safe-claude
    safe claude --dangerously-skip-permissions $argv
end

机器本地策略文件示例:

;; ~/.config/agent-safehouse/local-overrides.sb
;; 主机特定的例外情况，不应存在于共享仓库配置中。
(allow file-read*
  (home-literal "/.gitignore_global")
  (home-subpath "/Library/Application Support/CleanShot/media")
  (subpath "/Volumes/Shared/Engineering")
)

使用 --add-dirs-ro 或 --add-dirs 处理常规的共享文件夹访问，并使用 --append-profile 处理机器本地的策略例外或最终的拒绝/允许覆盖。当仓库是共享的，但每台开发者机器有不同的本地挂载点时，这种模式非常有用。

Git 工作树（Worktrees）会在启动时自动检测。