Agent Safehouse

为你的 macOS 本地 AI Agent 提供沙盒环境，使其仅能访问其真正需要的项目文件和集成服务。

Agent Safehouse 使用 macOS 的 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* 规则中的内置绝对路径。如果目标路径是符号链接（symlink），它会自动为真实目标路径生成匹配的授权。这既能保证特定于主机的系统文件正常工作，又无需将源配置文件扩大到递归的 /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）会在启动时自动检测。