Vibe 是一个在 Mac 上零配置启动 Linux 虚拟机、为 LLM Agent 提供沙箱的轻量工具：首次运行自动下载 Debian 基础镜像，通过内置脚本"配置（provision）"出可复用的模板镜像，启动时再复制为项目专属的.vibe/instance.raw实例磁盘。借助 APFS 的写时复制（Copy-on-Write）机制，20 GiB 的磁盘文件实际只占用约 2.5 GiB 空间——本文将带你一文看懂这套"模板镜像 + 实例磁盘 + 空间魔法"的完整体系。

1️⃣ 三层镜像体系：一图看懂 Vibe 的工作方式

Vibe 只做两件事：从 raw 磁盘镜像文件运行虚拟机，以及通过启动基础镜像、执行配置脚本、保存结果来**制备（provision）**模板镜像。整个体系可以分为三层：

Debian nocloud 压缩包（首次运行自动下载） │ 解压 ▼ 基础镜像 ~/.cache/vibe/*.raw ← 出厂系统 │ provision（跑 base.sh 等脚本） ▼ 模板镜像 ~/.cache/vibe/default.raw ← 装好工具链的"母盘"（可自定义多个） │ 复制到项目目录（APFS 写时复制，几乎瞬间完成） ▼ 实例磁盘 <项目>/.vibe/instance.raw ← 每个项目一份，状态持久保存

这种"母盘 + 副本"的设计带来三个好处：

• 启动快：复制磁盘文件在 APFS 上只是元数据操作，配合 M1 芯片，约 10 秒即可开机进入 shell；
• 隔离好：每个项目用各自的实例磁盘，Agent 装软件、改配置互不干扰；
• 可恢复：删掉.vibe/instance.raw即可从模板重新克隆一份"干净系统"。

2️⃣ 基础镜像：Debian nocloud，开机即 root

首次运行vibe时，程序会下载 Debian Linux 的nocloud基础镜像并解压为 raw 磁盘文件，缓存在~/.cache/vibe/目录下（见 src/main.rs 中 cache_dir 与 base_raw 的构造逻辑）。

为什么选 nocloud 而不是常见的 cloud 镜像？作者在文档中解释得很直白：nocloud开机直接就是 root 登录提示符，而 cloudinit 镜像启动时要等网络请求超时（离线时要等好几分钟），后续每次开机也更慢。

💡 基础镜像是"一次性原料"，日常使用你几乎不会直接碰到它。

3️⃣ 模板镜像：vibe provision的产物

模板镜像（template）= 基础镜像 + 一串配置脚本的运行结果。

默认的default.raw模板在首次启动时自动生成；你也可以制作自定义模板：

vibe provision --image my-template @rust @codex my-custom-script.sh

规则很简单：

脚本按顺序在虚拟机内执行，全部成功后才把磁盘保存为模板。制备流程的核心逻辑在 provision_image() 中：先把基础镜像复制到临时文件、扩容到 20 GiB，开机跑脚本，成功后再原子性地重命名为目标模板。

所有模板都会强制先执行基础脚本provisioning/base.sh，它会安装 build-essential、git、tmux、ripgrep、mise 等常用工具（见 base.sh#L95-L110），并扩展磁盘分区、设置主机名为vibe。内置的其他配置脚本包括：

• provisioning/rust.sh —— Rust 工具链
• provisioning/codex.sh —— Codex 环境
• provisioning/claude.sh、provisioning/gemini.sh、provisioning/pi.sh —— 各家 AI Agent 的环境

不想依赖默认脚本？可以直接拿任意.raw磁盘镜像放进~/.cache/vibe/，当作模板使用。

4️⃣ 实例磁盘：.vibe/instance.raw的诞生与生命周期

在项目目录里运行vibe，会发生这样的事：

1. 若项目里已有.vibe/instance.raw，直接使用它（--image参数被忽略）；
2. 否则把模板镜像复制到.vibe/instance.raw，打印Creating instance disk from ...；
3. 启动虚拟机，终端直接挂进 VM；
4. 你exit退出后，VM 关机，磁盘状态保留，下次vibe继续用同一块盘；
5. 手动删除.vibe/instance.raw后，下次启动会基于模板重新克隆一份。

关键实现在 ensure_instance_disk() 中，核心就三步：判断存在 → 建目录 →fs::copy模板到实例盘。

cd my-project && vibe --image my-template # 用自定义模板（仅限首次） vibe --cpus 4 --ram 4096 # 调整虚拟机资源

几个值得留意的细节：

• 实例盘名常量定义在 src/main.rs#L53（instance.raw），模板名常量在 src/main.rs#L51（default）；
• 默认挂载会把你宿主机上的~/.claude、~/.codex、~/.gemini等 Agent 目录共享进 VM，你可以精确控制 Agent"能看到什么"；
• 项目内的.git和.vibe子目录会被 tmpfs 遮盖，防止 VM 内直接读写。

5️⃣ APFS 写时复制：20 GiB 磁盘只占 2.5 GiB 的空间魔法

新 Mac 都使用 APFS（Apple File System），它是**写时复制（copy-on-write）**文件系统：文件中的"全零区域"不占实际存储空间。

因此 Vibe 默认的 20 GiB 实例磁盘，实际只消耗约 2.5 GiB：

$ ls -lah .vibe/instance.raw -rw-r--r-- 1 dev staff 20G Feb 11 21:57 .vibe/instance.raw $ du -h .vibe/instance.raw 2.5G .vibe/instance.raw

ls显示 20G，du却只有 2.5G——这正是"空间魔法"。磁盘空间只在你真正写入新数据块时才增长，这也是"从模板复制一份 20 GiB 母盘"几乎瞬间完成的原因。

如何扩容？如果 VM 内需要 100 GiB 空间，两步搞定：

# 1. 在 Mac 上把文件撑到 100G（依然是稀疏的，不占空间） truncate -s 100G .vibe/instance.raw # 2. 进入 VM 内扩展分区与文件系统 growpart /dev/vda 1 && resize2fs /dev/vda1

truncate只会把文件"声明"为 100G 大小，零区域依旧不占空间，这也是 APFS 稀疏文件的又一层魔法。

6️⃣ 常见场景速查：镜像体系操作清单

7️⃣ 延伸阅读：值得看的文件路径

• 主程序与镜像管理逻辑：src/main.rs（全文约 2000 行 Rust，含 provision/实例盘/启动全部流程）
• 内置配置脚本目录：provisioning/，基础脚本 provisioning/base.sh
• 用户态网络辅助程序（Go 编写）：helpers/vibe-usernet/
• 开发脚本与本地调试入口：scripts/vibe_dev、scripts/_common.sh
• 构建与工具链锁定：Cargo.toml、mise.toml

小结：Vibe 用"基础镜像 → 模板镜像 → 项目实例磁盘"的三层结构，把"给 LLM Agent 一个随便折腾的 Linux 沙箱"这件事做到了极致简单——复制一份母盘、APFS 帮你省空间、退出即保留、删除即重置。理解了这套镜像体系，你就掌握了 Vibe 全部的核心心智模型。🎉