Manage VMs
Run, attach to, share folders with, store, clone, resize and remove Lume VMs, change SIP, update Lume, and drive Lume from scripts or an AI client.
These are the everyday Lume commands. The examples use a VM named
macos-tahoe; use your own VM's name.
Inspect#
lume lslume get macos-tahoeget shows state, IP address, display, resources and SSH availability.
States: stopped, running, provisioning, and provisioning (stale) (an
operation died; check the logs and delete the VM).
Run, attach, stop#
lume run macos-tahoe # native viewer, attached to this terminal
lume run macos-tahoe --detach # background; logs in ~/Library/Logs/lume/
lume run macos-tahoe --display vnc # Screen Sharing instead
lume run macos-tahoe --display none # no viewer (alias --no-display)
lume run macos-tahoe --display none --vnc disabled # no VNC server at alllume attach macos-tahoe # reopen a viewer (--display native|vnc)
lume restart macos-tahoe # graceful, over SSH
lume shutdown macos-tahoe # graceful, over SSH
lume stop macos-tahoe # immediate- Closing the native window hides it; the guest keeps running.
- Every display mode starts a VNC server unless
--vnc disabled, which also turns off clipboard shortcuts in the native viewer and conflicts with--display vnc,--vnc-portand--vnc-password. - Drop files or folders from Finder onto the native viewer to copy them over
SSH to
/Users/lume/Desktop(existing names are never overwritten). - One
lume runprocess owns a VM. "Auxiliary storage is locked" means another one still runs:lume stopit first.
Share a folder#
lume run macos-tahoe --shared-dir ~/Projects
lume run macos-tahoe --shared-dir ~/Projects:roIt appears at /Volumes/My Shared Files. The native viewer's Share Folder
adds one while the guest runs, for that run only.
Store VMs elsewhere#
lume config storage add external /Volumes/External/lume
lume config storage list
lume config storage default external
lume run macos-tahoe --storage externalThe default store is ~/.lume. Run Lume as the user who owns it: sudo lume
looks in root's home and cannot see your VMs.
Clone and delete#
lume clone macos-tahoe macos-tahoe-backup
lume delete macos-tahoe-backupclone copies disk.img and nvram.bin together; never copy one without the
other. Disks are sparse, so host usage grows as the guest writes.
Grow a disk#
lume stop macos-tahoe
lume set macos-tahoe --disk-size 120GB --dry-run # validate only
lume set macos-tahoe --disk-size 120GB # add --keep-backup to keep the rollback copy
lume run --no-display macos-tahoe
lume ssh macos-tahoe 'diskutil info / | grep "Container Total Space"'You can only make a disk bigger. The VM must be stopped, use the standard disk
layout and have FileVault off, and the host macOS must be at least as new as the
guest. --no-backup skips the rollback copy. For a Linux guest, Lume grows the
disk image, and you then grow the partition and filesystem inside the guest.
See how disk growth works.
Turn SIP on or off#
System Integrity Protection (SIP) is macOS's protection for system files. The VM must be macOS and stopped, with a working admin account and Remote Login (unattended VMs already have both). Install the Recovery VNC driver once:
python3 -m pip install --user vncdotoollume sip off macos-tahoe
lume sip on macos-tahoe --admin-user admin --admin-password-stdin
printf '%s\n' "$LUME_ADMIN_PASSWORD" | \
lume sip off macos-tahoe --admin-user admin --admin-password-stdin --yesA successful run prints System Integrity Protection status: disabled. (or
enabled.) from a normal boot and leaves the VM stopped. The admin password can
use only lowercase letters, digits and hyphens, because Lume types it into
Recovery. To get many VMs with SIP off, change one seed VM and lume clone it.
See how SIP changes work.
Update Lume#
lume check-update
lume update --apply
lume channel set stable # or nightly; takes effect on the next updatecurl -fsSL https://cua.ai/lume/install.sh | bash -s -- --channel nightly
curl -fsSL https://cua.ai/lume/install.sh | \
LUME_VERSION=nightly-lume-v0.5.4-nightly.20260812.123456789 bash # pin one nightlyStable is the default. A pinned nightly does not change the saved channel.
Drive Lume from scripts and AI clients#
The HTTP API and the MCP server control the same VMs as the lume command. Use
the API from scripts and services, and MCP from AI clients.
Use the HTTP API#
The installer starts lume serve at login on port 7777. Install with
--no-background-service to start it yourself:
lume serve # localhost:7777
lume serve --port 7778curl http://localhost:7777/lume/vmsThe API listens on localhost only. Keep it there unless you have a network
boundary and a plan for authentication. Every endpoint is in the
HTTP API reference.
Connect an MCP client#
lume serve --mcp speaks MCP over stdio, so the AI client starts it. Use the
path that which lume prints:
{
"mcpServers": {
"lume": {
"command": "/Users/your-name/.local/bin/lume",
"args": ["serve", "--mcp"]
}
}
}Restart the client. It can then list, create, run, stop, clone and resize VMs, and run SSH commands in unattended guests (see the MCP tools). To test the server on its own:
npx @modelcontextprotocol/inspector lume serve --mcpThe MCP server can create and delete VMs and run commands in them. Configure it only for clients you trust, and give an agent its own VM.
Troubleshooting#
| Symptom | Fix |
|---|---|
| Auxiliary storage is locked | Another lume run owns the VM: lume stop <vm>. |
sudo lume cannot find a VM | Run as the user who created it. |
| SSH unavailable | Check lume get <vm> shows running with an IP; unattended VMs use lume / lume. |
| Sequoia shows an Accessibility step on first boot | Known (#2155); Tahoe is the verified preset. |