Lume 完全指南：在 Apple Silicon Mac 上用 CLI 创建与管理 macOS / Linux 虚拟机

Lume 完全指南：在 Apple Silicon Mac 上用 CLI 创建与管理 macOS / Linux 虚拟机

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua

Lume 是 CUA 生态下的本地虚拟机管理器，一个基于 Apple Virtualization.Framework 的命令行工具，用于在 Apple Silicon Mac（M1/M2/M3 及后续芯片）上创建、运行和管理 macOS 与 Linux 客户机。它把 IPSW 恢复镜像安装、SSH 接入、共享目录、VNC 自动化和 OCI 镜像分发打包进一套lume命令，并额外提供一个本地 HTTP API 供脚本和 AI 客户端调用。适用对象是在自己的 Mac 上需要可复现、可脚本化虚拟机环境的开发者与 AI 研究者，而不是寻求云桌面或图形化虚拟化管理的用户。主机要求：macOS 13.0 及以上、至少 8GB 内存（16GB 更从容）、至少 50GB 可用磁盘。

🖥️ 从 IPSW 到 SSH：搭建第一台干净的 macOS 虚拟机

本章解决"如何在本地从零得到一台开箱可用的 macOS 虚拟机"，也是三个典型场景里最常见的一条线。

场景一适合需要干净 macOS 环境的开发者：本地编译、跑 CI 复现用例，或者给 CUA 工作流提供一个可控的桌面。Lume 的tahoe预设走离线无人值守配置路径，不会通过显示界面去驱动 Setup Assistant。做法是先拿到 Apple 官方恢复镜像，再交给 Lume 创建：

下面两条命令在还没有下载过 IPSW、需要自动取到官方最新镜像地址时使用：

IPSW_URL="$(lume ipsw | tail -n 1)" curl -L "$IPSW_URL" -o ~/Downloads/macos-tahoe.ipsw

创建与启动一条线走完，预设会自动创建lume用户、开启 SSH、配置自动登录并禁用休眠与锁屏，初始账号密码均为lume/lume：

lume create macos-tahoe --ipsw ~/Downloads/macos-tahoe.ipsw --unattended tahoe lume run macos-tahoe lume ssh macos-tahoe 'sw_vers; id -un'

验证是否配置成功，直接执行一条 guest 内命令：lume ssh macos-tahoe 'sw_vers; id -un'能返回系统版本和用户即说明 SSH 已就绪。需要说明两点：tahoe是已验证的无人值守预设，sequoia预设可用，但首次显示启动时仍可能停留在 Setup Assistant 的可访问性步骤；macOS 虚拟机磁盘使用稀疏文件，宿主实际占用随 guest 写入增长，创建时指定的磁盘大小只是逻辑容量。

🔁 日常高频操作：Lume 虚拟机生命周期与运维命令

本章覆盖装完之后的日常：状态查询、资源调整、SSH 远程执行、快照备份与镜像分发。

lume run默认打开原生查看器，同时保留 VNC 监听供自动化使用；--display vnc打开屏幕共享，--display none（或--no-display）则完全不弹查看器。需要主机与虚拟机之间交换文件时，--shared-dir接受路径:ro或路径:rw指定读写权限：

lume run macos-tahoe --display none --shared-dir ~/codebase:ro

生命周期与运维命令速查：

镜像管理走 OCI 容器注册表协议，适合把配置好的环境当作制品分发：拉取时用lume pull <image> [name]（默认 registry 为ghcr.io），把本机 VM 推出去用lume push <name> <image:tag>，lume prune清理本地缓存。Linux 虚拟机还支持--mount附加只读磁盘镜像、--usb-storage以 USB 大容量存储方式挂载磁盘，这些是 Linux guest 专属能力。

⚙️ 定制与约束：资源调整、SIP 策略与本地 API

本章解决"超出基础流程的定制需求"：改配置、改 SIP、以及把 Lume 暴露给工具链。

资源方面，lume set可以在不重建虚拟机的情况下调整 CPU 与内存；磁盘扩容是只增不减的，且要求 VM 处于停止状态。macOS 布局（ISC、主 APFS、RecoveryOS）下，首次扩容需要预留足够空间重定位 RecoveryOS，Lume 会报出可接受的最小总容量；Linux 侧只增大镜像文件，分区与文件系统需在 guest 内自行扩展。宿主 macOS 版本必须不低于 guest。

SIP（系统完整性保护）的变更不需要手动进恢复模式：lume sip通过配对的恢复会话完成策略切换，仅支持已停止的 macOS VM，Tahoe 是当前验证过的流程；命令可选用pip3 install vncdotool提供的 Recovery VNC 输入能力：

lume sip off macos-tahoe

作为自动化底座，lume serve --port 7777启动本地 VM 管理 HTTP API，lume logs查看守护进程日志，MCP 文档见 docs/content/docs/how-to-guides/lume/use-mcp-server.mdx。注意：并发上限是每台宿主最多 2 个 macOS guest，内存、磁盘和 CPU 容量可能进一步压低这个数字。

隐私上，Lume 遥测默认开启，只记录伪匿名的安装、版本、命令与 API 事件元数据，不收集提示词、VM 名称、文件路径或 VM 内容。若不需要，用lume config telemetry disable关闭，status子命令可随时查看当前状态，reset-id删除安装标识。

🧯 常见问题快速排查

本章汇总文档里明确记录的几类失败，按"症状→原因→验证"给出处理方式。

• 症状：sudo lume提示找不到虚拟机。原因是 VM 默认存放在当前用户 home 目录下，sudo切换了HOME，root 进程看到的是另一个存储位置。验证：始终用创建 VM 的账号运行，lume ls能列出该 VM 即正常。
• 症状：提示辅助存储被锁定。原因是同一台 VM 同时只能有一个进程运行。处理：

lume ls lume stop macos-tahoe

之后再重试lume run。

• 症状：磁盘扩容被拒绝。除上面提到的停止要求与 FileVault 加密 guest 不支持外，还需核对宿主 macOS 版本是否不低于 guest；lume set配合--dry-run可以先验证扩容方案而不实际改动磁盘。

下一步建议：

• 完整命令与参数以 docs/content/docs/reference/lume/cli-reference.mdx 为准，lume dump-docs可直接导出 JSON 供工具链集成；
• 想把 AI 客户端接到本地 VM，看 docs/content/docs/how-to-guides/lume/use-mcp-server.mdx 与 docs/content/docs/reference/lume/http-api.mdx；
• 版本确认用lume --version，更新检查用lume check-update，应用更新用lume update --apply。

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua