使用 Lima 在虚拟机沙箱中安全运行 AI Agent：隔离挂载、安装部署与工作目录双向同步实战

Lima（Linux virtual machines, with a focus on running containers）提供了一种将 AI Agent（如 Claude Code、Codex、Gemini、Aider、GitHub Copilot、OpenCode）封装进 Linux 虚拟机运行的方案，从文件系统层面阻止 Agent 直接读写或执行宿主机的文件。本文基于仓库文档 website/content/en/docs/examples/ai.md，完整覆盖"仅挂载项目目录"的最小暴露配置、六类主流 AI Agent 的安装与认证步骤，以及 limactl shell --sync 工作目录双向同步机制，并结合 cmd/limactl/shell.go 与 cmd/limactl/editflags/editflags.go 源码解读其底层约束，帮助读者在宿主与 AI Agent 之间建立一条可控、可审计、可回滚的文件操作通道。

为什么把 AI Agent 关进虚拟机

Lima 官方文档明确给出了动机：在虚拟机内运行 AI Agent，可以防止 Agent 直接读取、写入或执行宿主机文件（参见 ai.md）。AI 编程助手在被赋予任意文件权限后，可能修改宿主机上的配置、删除文件或在宿主机上执行意外命令；将这些工具隔离进 VM，宿主机上只有你明确暴露出去的目录才可见，相当于给 Agent 加了一道"最小权限边界"。

从 cmd/limactl/shell.go 的源码可以看出，这一隔离思路甚至被硬编码进了 CLI 行为：当使用 --sync 时，实例配置了任何 host mounts 会直接报错；当实例是 wsl2 VM 类型时也会报错，因为 wsl2 的 guest 可以通过 /mnt 自动挂载访问宿主目录，无法像其他 VM 类型那样隔离宿主文件。可见"隔离宿主文件系统"是 Lima 沙箱运行 Agent 的设计前提。

最小暴露原则：只把当前项目目录挂进 VM

官方强烈建议：运行 AI Agent 时，只将你的项目目录（即当前目录）挂载进 VM，而不是整个 home 目录。这可以通过 limactl start 的挂载参数在创建实例时一次性完成。

Lima v2.0+ 语法

limactl start --mount-only .:w

• --mount-only 表示"在覆盖已有挂载的基础上追加"，即实例最终只保留本次指定的挂载项；
• .:w 表示挂载当前目录，且 :w 后缀表示可写（writable）；
• 去掉 :w 即为只读模式，Agent 只能读取项目文件，无法回写。

Lima v1.x 语法

limactl start --set ".mounts=[{\"location\":\"$(pwd)\", \"writable\":true}]"

• 通过 --set 直接把 .mounts 数组覆盖为只含当前目录的一条记录；
• 将 writable 改为 false 即为只读模式。

挂载参数背后的实现

挂载相关的三个参数 --mount、--mount-only、--mount-none 都定义在 cmd/limactl/editflags/editflags.go：

• --mount：追加挂载目录，:w 后缀表示可写（兼容 colima 的写法）；
• --mount-only：与 --mount 类似，但覆盖已有挂载；
• --mount-none：移除所有挂载。

从源码看，--mount-only 与 --mount 互斥（同时指定会报 "flag --mount conflicts with --mount-only"），而 --mount-none 与二者也不兼容；这些参数最终会被翻译成 YAML 表达式写入实例配置，例如 --mount-only /foo --mount-only /bar:w 会生成：

.mounts = [{"location": "/foo", "mountPoint": "/foo", "writable": false},{"location": "/bar", "mountPoint": "/bar", "writable": true}]

（该行为有单元测试佐证，见 editflags_test.go。）因此在 v2.0+ 上，--mount-only .:w 实际上等价于"先把实例配置中的 mounts 清空，再写入当前目录这一条记录"。

在 VM 内安装与认证六大 AI Agent

官方文档为以下 Agent 提供了统一的安装模式：先用 lima 命令进入 VM 执行安装，再在首次会话中完成认证。所有命令前的 lima 前缀表示在虚拟机内执行。

补充说明（来自文档注释）：Node.js 通过 snap 而非 apt 安装，是因为 AI Agent 通常需要非常新版本的 Node.js。

通用环境变量注入方式

各 Agent 的 API Key 可以通过编辑 guest 内用户的 shell 配置文件持久化。由于 guest 用户名与宿主机用户名相同，v2.1 GA 之前文档建议的路径为 /home/${USER}.linux/.bash_profile（其中 .linux 是 guest 用户名后缀）：

lima vi "/home/${USER}.linux/.bash_profile"

在其中追加形如 export ANTHROPIC_API_KEY=...、export OPENAI_API_KEY=...、export GEMINI_API_KEY=...、export GH_TOKEN=... 的环境变量即可。

Aider

lima sudo apt install -y pipx
lima pipx install aider-install
lima sh -c 'echo "export PATH=$PATH:$HOME/.local/bin" >>~/.bash_profile'
lima aider-install
lima aider

首次会话中按照提示完成认证。Aider 通过 pipx 安装，因此需要把 $HOME/.local/bin 加入 PATH。

Claude Code

lima sudo snap install node --classic
lima sudo npm install -g @anthropic-ai/claude-code
lima claude

首次会话中按照提示完成认证；或通过 export ANTHROPIC_API_KEY... 注入 API Key。

Codex（OpenAI）

lima sudo snap install node --classic
lima sudo npm install -g @openai/codex
lima codex

首次会话中按照提示完成认证；或通过 export OPENAI_API_KEY... 注入 API Key。

Gemini

lima sudo snap install node --classic
lima sudo npm install -g @google/gemini-cli
lima gemini

首次会话中按照提示完成认证；或通过 export GEMINI_API_KEY... 注入 API Key。

GitHub Copilot

lima sudo snap install node --classic
lima sudo npm install -g @github/copilot
lima copilot

在首次会话中输入 /login 完成认证；或通过 export GH_TOKEN=... 注入令牌。

OpenCode

lima sudo snap install node --classic
lima sudo npm install -g opencode-ai
lima opencode

与其他 Agent 不同，OpenCode 在首次会话中输入 /connect 完成连接，但这一步对 OpenCode 并非必需。

工作目录双向同步：limactl shell --sync

官方文档为"在 VM 内运行 AI Agent"提供了第二层安全机制——--sync 标志。它要求 Lima >= 2.1，功能是在宿主机工作目录与 guest VM 之间做双向同步：Agent 在 guest 内对项目文件的修改，只有在宿主侧确认后才会合并回来。这对"防止 Agent 意外破坏宿主文件"尤其有用。

与 mount 的对比

特性	挂载（--mount/--mount-only）	同步（--sync）
用途	让宿主目录在 guest 内可见（开启写模式后为双向）	工作目录的临时双向同步（guest 侧变更经确认后合并回宿主）
实时更新	是	否
安全性	较低（Agent 可直接访问宿主文件）	较高（变更在应用到宿主前会被审查）
需要 rsync	否	是

典型场景：安全运行 AI 代码助手

官方给出了完整的四步流程：

1. 创建无宿主挂载的隔离实例

limactl start --mount-none template:default

--sync 要求实例没有任何宿主挂载，因此创建时必须用 --mount-none 显式关闭所有 mounts。

2. 进入项目目录

cd ~/my-project

3. 运行 AI Agent 修改代码

让 Agent 直接执行一条命令并退出：

limactl shell --sync . default claude "Add error handling to all functions"

或直接进入同步 shell 交互操作：

limactl shell --sync . default

其中 --sync . 表示同步当前目录，default 是实例名。

4. 审查并接受变更

命令退出后会出现交互式确认提示：

⚠️ Accept the changes?
→ Yes
  No
  View the changed contents

• Yes：把变更同步回宿主机，并清理 guest 内的同步目录；
• No：丢弃全部变更，清理 guest 内的同步目录；
• View the changed contents：先查看 Agent 改动内容的 diff，再决定接受与否。

--sync 的源码级约束

--sync 的底层实现位于 cmd/limactl/shell.go，源码明确规定了以下前置条件：

1. 宿主机与 guest 都必须安装 rsync。shell.go 在启用同步时会执行 exec.LookPath 检查 rsync 是否存在，缺失直接报 "rsync is required for --sync but not found"；rsync 后端是 pkg/copytool/copytool.go 中定义的 BackendRsync，同时会检查 guest 侧是否可用（"rsync not available on guest(s)"）；
2. 宿主工作目录至少要有 4 层深度，例如 /Users/username/projects/myproject。源码中对应常量 rsyncMinimumSrcDirDepth = 4（注释说明 /Users/USER 的深度是 3，故至少需要 4 层），Windows 上路径深度计算另有处理；
3. 实例不得配置任何宿主挂载，否则报错 "cannot use --sync when the instance has host mounts configured, start the instance with --mount-none to disable mounts"（limactl start --mount-none 正是为此设计的）；
4. 实例不得使用 wsl2 VM 类型，因为 wsl2 的 guest 已通过 /mnt 自动挂载看到宿主目录，--sync 无法起到隔离作用。

这些硬性校验保证了 --sync 的语义不会因实例配置差异而被破坏，也让上述使用步骤有了明确的失败排查方向。

延伸阅读

• 配置 » AI agents inside Lima：Agent 运行在 VM 内的场景总览，本指南即属此类别；
• 配置 » AI agents outside Lima (MCP)：自 Lima v2.0 起，可从 VM 外部通过 Model Context Protocol（MCP）工具在沙箱内读写、执行本地文件，即 Agent 在宿主侧、文件操作在 VM 内的反向模式；
• 配置 » GPU：为 VM 内 Agent 配置 GPU 加速；
• 相关 CLI 实现：cmd/limactl/shell.go（--sync 逻辑）、cmd/limactl/editflags/editflags.go（--mount/--mount-only/--mount-none 解析）。