代理安全屋

在 macOS 上为您的 LLM 编码代理创建沙箱环境，使其仅能访问实际所需的文件和集成。

Agent Safehouse 使用 sandbox-exec 结合可组合的策略配置文件，并采用“默认拒绝”模型。它包含针对主流编码代理及应用托管代理工作流的配置文件，同时确保常规开发使用依然便捷高效。

安装

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 的设计基于实用的最小权限原则：

• 从“全部拒绝”开始。
• 仅允许代理完成有用工作所需的权限。
• 保持开发者工作流程的高效性。
• 默认情况下轻松降低风险。

它是一个加固层，而非能够抵御蓄意攻击者的完美安全边界。

默认 HOME 目录访问权限

HOME_DIR 用于在组装的策略中生成精确的、相对于主目录的规则。但仅凭这一点，并不会授予对您主目录的递归读取权限。

Safehouse 的默认行为更为严格：

• 对 /、$HOME 路径以及 $HOME 本身仅允许元数据级别的遍历，以便运行时可以探测明确允许的主目录范围路径。
• 允许读取 ~/.config 和 ~/.cache 目录的根目录内容，以便工具能够发现 XDG 位置。
• 从始终启用的配置文件中，明确允许访问少数几个与主目录相关的文件或目录，例如 Git/SSH 元数据以及共享的代理指令文件夹。

实际上，即使执行 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 shell（zsh / bash）：

# ~/.zshrc 或 ~/.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 工作树会在启动时自动检测：如果所选工作目录本身就是 Git 工作树的根目录，则该工作树将获得其所需的共享 Git 元数据访问权限，即使其共同目录位于所选工作目录之外。同时，该仓库的其他现有关联工作树也会默认变为可读，便于跨工作树检查。不过，这一快照不会更新给已经运行的进程。因此，如果您在稳定的父目录下创建工作树，例如 ~/worktrees，建议显式使用 --add-dirs-ro 添加该根目录。

所有详细文档（安装、使用、选项、架构、测试、调试和调查）均收录在 VitePress 文档站点中。

Agent Safehouse 快速上手指南

Agent Safehouse 是一款专为 macOS 设计的沙盒工具，用于限制 LLM 编程助手（如 Claude Code、Codex 等）的文件访问权限。它采用“默认拒绝”模型，确保 AI 代理只能访问其工作所需的特定文件和集成，从而在保障开发效率的同时降低安全风险。

环境准备

• 操作系统：macOS
• 前置依赖：
  • 系统内置的 sandbox-exec 工具（macOS 自带，无需额外安装）
  • 包管理器 Homebrew（推荐用于安装）或基础的 Shell 环境（bash/zsh/fish）

安装步骤

你可以选择通过 Homebrew 或直接下载脚本进行安装。

方式一：使用 Homebrew（推荐）

brew install eugene1g/safehouse/agent-safehouse

方式二：独立脚本安装

如果你不想使用 Homebrew，可以手动下载可执行脚本：

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

提示：请确保 ~/.local/bin 已添加到你的 $PATH 环境变量中，以便直接在终端运行 safehouse 命令。

基本使用

Agent Safehouse 的核心用法是在启动 AI 代理命令前加上 safehouse 前缀。它会自动加载针对主流编程助手的预设策略配置文件。

最简单的使用示例

假设你正在使用 claude 命令（例如 Claude Code CLI），只需在其前方加上 safehouse：

safehouse claude --dangerously-skip-permissions

工作原理：

• 该命令会启动一个沙盒环境。
• 默认情况下，AI 代理无法读取你的主目录（$HOME）中的文件，除非策略明确允许。
• 它仅允许访问必要的元数据（如 Git/SSH 配置）和特定的缓存目录，防止意外泄露敏感文件（如 ~/.ssh/id_rsa 或未授权的代码库）。

自定义只读访问目录

如果你需要让 AI 代理访问特定的项目目录（例如 /Users/name/projects/my-app），可以使用 --add-dirs-ro 参数：

safehouse \
  --add-dirs-ro="$HOME/projects/my-app" \
  claude --dangerously-skip-permissions

进阶：配置本地别名（可选）

为了方便日常使用，建议在 Shell 配置文件（如 ~/.zshrc）中添加别名：

# ~/.zshrc
alias safe-claude='safehouse claude --dangerously-skip-permissions'

保存并生效配置后，即可直接运行：

safe-claude

这样既保持了命令的简洁性，又确保了每次运行都在安全的沙盒环境中。