webcoyote/sandvault

SandVault – macOS 上的沙盒化 AI 代理与 shell 命令

是什么 – SandVault (sv) 是一个命令行工具，创建一个轻量级、受限的 macOS 用户账户，并在该账户内运行命令（包括 Claude、Codex、Gemini 等流行的代码生成代理）。它结合了 macOS 的 sandbox-exec 与独立用户，实现了类似虚拟机的隔离，但无需完整虚拟机的开销。

核心功能

• AI 就绪 – 一键快捷启动流行的代码代理（Claude、OpenAI Codex、OpenCode、Google Gemini、pi、Muse Code），可从主机或沙盒内启动。
• Web 与 iOS 自动化 – 沙盒可通过 Chrome DevTools 协议与主机上的无头 Chrome（或 Lightpanda）通信，也可通过 HTTP 桥接控制 iOS 模拟器，实现网页和 iOS 应用的 UI 自动化测试。
• 快速上下文切换 – 由于仅切换 macOS 用户，启动沙盒会话几乎瞬时完成，远快于启动虚拟机。
• 免密码切换 – 初始设置后，可通过 sudo -u sandbox-$USER … 模拟沙盒用户，或通过 SSH 无交互式密码访问。
• 共享工作区 – /Users/Shared/sv-$USER 下的目录对主账户和沙盒账户均具有写权限，便于文件或 Git 仓库交换。
• 纵深防御 – 沙盒用户无法访问你的主目录、其他用户、挂载的磁盘或系统文件；仅可见少数只读系统路径。
• 干净卸载 – sv uninstall 会移除沙盒用户及其所有文件，但共享工作区保持不变。

使用方法

# 在沙盒内启动 Claude
sv claude
# 在沙盒内运行 shell 命令
sv shell /Users -- pwd
# 克隆仓库到共享区域并在那里启动代理
sv-clone https://github.com/example/repo.git -- codex

你还可以添加 --ssh 通过 SSH 连接到沙盒用户运行命令，或设置 SANDVAULT_ARGS 使 --native-install（在沙盒内安装代理）等选项成为默认值。

安装 – 可通过 Homebrew（brew install sandvault）安装，或克隆仓库并将 sv 脚本添加到 $PATH。

高级功能

• 原生安装 – 代理可通过其自带安装器在沙盒内安装（sv -N claude）。
• 浏览器自动化 – 启动无头 Chrome（或 Lightpanda），并通过 SV_BROWSER_ENDPOINT 环境变量从沙盒连接；支持 Playwright 或 Puppeteer。
• iOS 模拟器自动化 – 主机上启动一个全新模拟器，并通过 HTTP 桥接暴露（SV_IOS_SIMULATOR_ENDPOINT）。可通过简单的 curl 命令查询可访问性树、点击元素、启动应用、截取屏幕截图。
• SSH 密钥管理 – 将公钥放入 ~/.config/codeofhonor/sandvault/authorized_keys.d/，SandVault 会自动重建沙盒用户的 authorized_keys。
• AgentsView 集成 – 若使用 AgentsView 仪表板，sv-agentsview-setup 会镜像沙盒会话数据，使你可将 AI 代理活动与主机会话一同查看。

限制

• GUI 应用无法在沙盒内运行，因为 macOS 禁止不同用户连接到 WindowServer。
• 不支持嵌套 sandbox-exec；对于 swift 等工具，必须通过环境变量标志禁用其内部沙盒，或使用 --no-sandbox（-x）运行 SandVault。

适用人群 – 希望在隔离环境中实验强大 AI 代码代理或自动化浏览器/iOS 模拟器的开发者。在 Docker 风格容器沉重或不可用的 macOS 环境中尤其有用。

---

TL;DR – SandVault 是 macOS 专用 CLI，创建受限用户账户，允许你在沙盒中运行 AI 代码代理、shell 命令、无头 Chrome 和 iOS 模拟器自动化，并通过 Homebrew 实现简易安装/卸载。