workmux 沙盒安全指南：如何用 Docker 容器 / Lima VM 隔离运行 AI Agent

【免费下载链接】workmuxgit worktrees + tmux windows for zero-friction parallel dev项目地址: https://gitcode.com/gh_mirrors/wo/workmux

workmux 是一款基于 git worktrees + tmux 的并行开发工具，其**沙盒（sandbox）**功能可将 AI Agent 隔离运行在Docker 容器或Lima 虚拟机中，让 Agent 无法触碰你主机上的 SSH 密钥、AWS 凭证等敏感文件。本指南将带你快速理解 workmux 沙盒的安全模型、两种后端的差异，以及 Docker 容器与 Lima VM 的最小配置步骤。

1️⃣ 为什么 AI Agent 需要沙盒？

AI Agent 通常以"自动批准"模式运行（如 Claude 的--dangerously-skip-permissions），这意味着它可以自主执行命令、读写文件。如果直接跑在宿主机上，一次误操作就可能读到~/.ssh、~/.aws里的凭证。

workmux 的做法是把隔离边界从 Agent 自身前移到环境：

• 启用沙盒后，workmux 会自动开启各 Agent 的非交互批准模式，由容器/VM 作为安全边界，而不是依赖 Agent 自己的权限弹窗；
• 沙盒内只挂载当前 worktree（读写）、Git 运行数据和 Agent 凭证目录，主机上的 SSH 密钥、GPG 密钥、其他项目的.env等文件根本不存在于沙盒内；
• 状态指示、仪表盘、合并、派生新 Agent 等所有功能跨沙盒边界照常工作，由内置 RPC 桥保持同步。

2️⃣ Docker 容器 vs Lima VM：选哪个后端？

建议：容器是更好的默认选择——配置简单、用完即毁；如果你需要持久 VM 和 Nix/Devbox 工具链，选 Lima。

3️⃣ Docker 容器后端：最快配置步骤

第 1 步：安装容器运行时（Docker、Podman 或 macOS 26+ 的 Apple Container），然后第 2 步：在配置文件中开启沙盒：

# ~/.config/workmux/config.yaml 或 .workmux.yaml sandbox: enabled: true

预构建镜像会在首次运行时按你配置的 Agent 自动拉取，无需手动构建。常用辅助命令：

workmux sandbox pull # 手动拉取最新沙盒镜像 workmux sandbox shell # 进入容器调试环境

进阶安全选项（均只能写在全局配置中，项目配置无法削弱安全边界）：

• 隐藏敏感文件：container.excluded_files列出.env、.env.local后，它们会被只读/dev/null遮蔽，Agent 读不到；
• 更强的 VM 边界：设置container.oci_runtime: kata，让容器运行在 Kata 硬件虚拟机下，复用完全相同的镜像与挂载方案；
• 自定义镜像：workmux sandbox init-dockerfile导出 Dockerfile（参考仓库中预置的 docker/Dockerfile.claude），加入自己的编译器和构建工具后重新构建即可。

4️⃣ Lima VM 后端：最快配置步骤

第 1 步：安装 Lima（brew install lima），第 2 步：指定后端：

sandbox: enabled: true backend: lima lima: cpus: 8 memory: 8GiB provision: | sudo apt-get install -y ripgrep fd-find jq

首次使用时 VM 会自动创建、provision 并启动，无需手动管理生命周期。两个关键点要知道：

• Git 元数据边界：Lima 采用宽写挂载，无法把 Git 策略文件单独设为只读，因此 workmux 会要求你显式确认接受这一减弱的隔离（可写lima.accept_reduced_git_metadata_isolation: true免交互）。若必须保护宿主机 Git 元数据，请改用 Docker/Podman/Apple Container；
• 工具链开箱即用：项目根目录有devbox.json或flake.nix时，Agent 命令自动包进devbox run/nix develop，声明的编译器、linter 立即可用，且/nix/store跨会话缓存。

日常运维：workmux sandbox stop释放资源、workmux sandbox prune清理闲置 VM 回收磁盘。

5️⃣ 网络域名白名单：阻止 Agent 外泄数据

默认容器网络是放开的。开启出站域名白名单后，Agent 只能访问你批准的域名：

sandbox: enabled: true network: policy: deny allowed_domains: - "api.anthropic.com" # 换成你的 Agent API 域名

其实现是双层强制：容器内 iptables 防火墙阻断一切直连出站，流量被强制导到宿主机的 CONNECT 代理，由代理校验域名白名单并拒绝私有/内网 IP。即使 Agent 故意忽略代理环境变量也绕不过去。

⚠️ 注意：限制模式下只放行 HTTPS(443)，git+ssh会被阻断，请改用 HTTPS 远端。

6️⃣ 你必须了解的安全边界

沙盒 ≠ 银弹，理解"能挡什么、挡不住什么"比配置更重要：

• Agent 仍可编辑 Git 仓库：这些改动本质上是不可信的，后续构建/测试时可能以你的主机用户身份运行。如果你的威胁模型要求"沙盒 Agent 对宿主机代码零影响"，不要用 workmux 沙盒；
• host_commands 是便利性功能：允许沙盒内代理执行宿主机命令（如just、cargo），被代理的命令可在项目文件中执行代码，需要严格隔离时不要开启；
• 对比 Agent 自带沙盒：Claude Code 内置沙盒只是进程级限制（仅约束 Bash 工具，~/.ssh默认仍可读）；workmux 沙盒是完整环境隔离，未挂载的文件在沙盒里根本不存在，是更强的保证。详见 docs/src/content/docs/guide/sandbox/alternatives.md。

7️⃣ 常见排障速查

📖 完整文档：沙盒总览 · 容器后端 · Lima 后端 · 共享特性 · sandbox 命令参考

核心实现位于 src/sandbox/mod.rs、src/sandbox/container.rs 与 src/sandbox/lima/mod.rs，欢迎深入源码或提交 Issue 讨论。

【免费下载链接】workmuxgit worktrees + tmux windows for zero-friction parallel dev项目地址: https://gitcode.com/gh_mirrors/wo/workmux