devvm 教程:给 Claude Code 开一台项目虚拟机

让 Claude Code 在项目里自己跑 npm install、改文件、连网络,等于把你的整台电脑借给它。devvm(MIT 许可,11 月 6 日发 v0.1.0)的做法是给每个项目文件夹单独开一台虚拟机,Agent 只在里面干活。这篇按官方 README 和文档,把从安装到把成果取回宿主机的整条路径走一遍。
先分清:它挡什么,不挡什么
官方《Staying safe》一页把边界说得很直接:安装依赖、项目代码和 Agent 都跑在虚拟机里,你没写过的代码读不到你的凭据,也没法在宿主机上触发 git hook,更碰不到其他项目。虚拟机有自己的内核,所有保证都建立在这道边界上。
| 东西 | 虚拟机能不能碰 |
|---|---|
| 当前项目文件夹 | 可读写;用 --clone 时改为它自己的克隆,不挂载你的文件夹 |
| 主目录里的其他文件、其他项目 | 不挂载,碰不到 |
| GitHub 令牌、Claude Code 令牌、Codex 与 opencode 登录 | 留在宿主机,由代理在请求里填入,虚拟机只拿到占位符 |
| Agent 的设置、Skill | 从 devvm 自己的 Agent 仓库只读挂载,不含你的历史记录 |
| SSH 密钥 | 默认碰不到,只有打开 devvm ssh-agent 才可用 |
最后一点官方也写明了:虚拟机能做到它的密钥允许的一切,哪怕它从没见过密钥。令牌权限给大了,被挡在外面的东西又回来了。
第一步:安装并自检
前置条件:macOS 13 及以上,或 Linux,arm64 或 x86_64,底层需要 Lima 2.2 或更新版本。官方写明在 Apple 芯片 Mac 以及 arm64 和 x86_64 的 Linux 上测过,Intel Mac 暂时没测。
macOS 用 Homebrew,会一并装上 Lima:
brew trust --formula devvmhq/tap/devvm
brew install devvmhq/tap/devvm
Linux(macOS 也可以)用安装脚本,装 Lima、QEMU 或开放 /dev/kvm 前都会先问你:
curl -fsSL https://github.com/devvmhq/devvm/releases/latest/download/install.sh | bash
每个发布版本都用 devvm 的 minisign 密钥签名,文档《Checking the install script》教你在跑脚本之前先验签,习惯这么做的话可以照着来。装完跑一次:
devvm doctor
它会检查机器上缺什么,并告诉你怎么补。
第二步:在项目目录开出第一台虚拟机
cd ~/some-project
devvm
第一次运行会先问几个问题,决定之后所有新虚拟机的默认值:虚拟机大小、预装哪些编程 Agent、基础镜像要不要带可选的附加项。随后构建一次基础镜像,官方说要几分钟;之后每台新虚拟机都是这份镜像的副本,几秒就起来,各种工具链在虚拟机之间只读共享。
接着 devvm 会列出这个文件夹的新虚拟机会装什么:它按项目文件识别工具链,目录里有 package.json 就装 node。你可以直接确认,也可以进入自定义,挑工具链、Agent、层、网络档位和大小。确认后你会进到虚拟机的 shell,路径和宿主机上一样,提示符以 (devvm) 开头:
(devvm) ~/some-project $ claude
支持的 Agent 是 Claude Code、Codex、opencode 和 pi,不需要在宿主机上装,devvm 在虚拟机里装。想在已有虚拟机里加一个:devvm tools add opencode。再次在同一个文件夹运行 devvm,打开的还是同一台虚拟机。
Claude Code 第一次启动前需要登录。文档给的办法是在虚拟机里运行 devvm agent login claude,登录凭据保存在宿主机的 ~/.local/share/devvm/logins/claude/,只有你自己能读(目录权限 700,文件权限 600)。已经在宿主机上配好的 Agent,可以用 devvm agent import 把设置复制进 devvm 的仓库,这一条命令会读你主目录里的 ~/.claude 等文件,其余时候 devvm 不碰它们。
第三步:弄明白四档网络
每台虚拟机的网络都经过宿主机上为它单开的代理,档位决定代理放行什么:
| 档位 | 虚拟机能访问 | 被限制在代理内 |
|---|---|---|
| open | 宿主机能访问的一切,包括 localhost 和局域网 | 否 |
| internet | 任意公网主机、任意端口,不含宿主机地址 | 是 |
| allowlist(默认) | 只有白名单里的主机 | 是 |
| none | 只有 Agent、密钥、登录和链接所需的主机 | 是 |
官方建议新手停在 allowlist 或 none,并且白名单越短越好:数据被偷时,只能发往你放行过的主机。换档位用 devvm network,例如 devvm network internet;想改所有新虚拟机的默认档位,用 devvm network -g none。受限档位之间切换立刻生效,进出 open 要等虚拟机下次启动。
各 Agent 自己的主机已经在白名单里:Claude Code 是 api.anthropic.com、claude.ai、downloads.claude.ai、platform.claude.com 和 mcp-proxy.anthropic.com;Codex 是 api.openai.com、chatgpt.com 和 auth.openai.com;opencode 只带自己的服务,所以你要给它的模型供应商放行,比如 devvm network allow api.anthropic.com。Claude Code 的遥测主机没进白名单。
第四步:不信任的仓库或 Agent,用 --clone
默认情况下虚拟机挂载你的项目文件夹,它写的文件你的编辑器马上看到。要跑来路不明的仓库,或者关掉了确认的 Agent,官方的建议是改用克隆:
devvm --clone # 虚拟机有自己的克隆,并打开其中的 shell
git fetch devvm # 之后在宿主机上,把虚拟机的成果取回为 devvm/<分支>
git log -p main..devvm/main # 合并之前先审
此时虚拟机碰不到你的工作区和 .git,成果只有在你 fetch 时才进仓库。fetch 本身不会在宿主机上运行虚拟机里的任何东西,只收对象、更新 devvm/* 分支;但这些提交要当作陌生贡献者的分支来审,审完再 merge 或 checkout。
几个官方点到的细节:已被 git 忽略的 .env 和 node_modules 不会复制进克隆;有未提交的改动,devvm 会提醒,提交后可以用 git push devvm 分支名 送进去;想让多个 Agent 在同一台克隆虚拟机里并行,每个用自己的 git worktree,放在克隆里的 .worktrees/名字 下,各自装各自的依赖,别共用一个 node_modules。
官方把话说在前头:没有任何沙箱能堵住所有缺口,几条习惯能补上 devvm 自己补不了的部分。
常见坑
- Claude Code 起不来,提示没登录。先在虚拟机里跑
devvm agent login claude,不要把令牌写进项目文件夹。 - 安装依赖或调接口被拒。白名单档下没放行的主机会被代理直接返回 403。看清被拒的主机名,再用
devvm network allow <主机>放行,别图省事直接切到 open。 - 以为 .env 被保护了。项目文件夹里的所有文件,包括
.env,虚拟机都看得见,和网络档位无关。凭据放在项目文件夹之外,Agent 仓库的设置目录里也别放。 - git fetch devvm 连不上。虚拟机必须在运行,已停止的虚拟机没有 SSH 条目;另外
~/.ssh/config需要 devvm 的 Include 行,没加时可以用GIT_SSH_COMMAND='ssh -F ~/.local/share/devvm/ssh_config' git fetch devvm。 - SSH agent 转发开着。官方建议保持关闭,或只给虚拟机一个装了必要密钥的 devvm 自己的 agent。GitHub 令牌用细粒度的,只绑这台虚拟机需要的。
完成标准
devvm doctor没有报缺项。- 在项目目录运行
devvm,提示符带(devvm),能在里面启动claude或你选的 Agent。 devvm network显示的档位是 allowlist 或 none,白名单里没有你说不出理由的主机。- 对不信任的仓库,已经用
devvm --clone开过一次,并能用git log -p main..devvm/main看到虚拟机的提交。 - 项目文件夹里没有
.env之类的凭据文件。
它和权限规则是两层:规则管 Agent 能不能做某件事,虚拟机管做错了影响多大。关于规则这一层,可以看站内的 Claude Code 权限自查 和 settings 权限配置;快讯版见 devvm 开源:一项目一台虚拟机关住 Agent。
最后
今天就挑一个你平时让 Agent 乱跑的项目,装好 devvm,用默认的白名单档把它搬进虚拟机,跑一次 devvm --clone 再 fetch 回来审一遍。