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 ls
lume get macos-tahoe

get 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 all
lume 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-port and --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 run process owns a VM. "Auxiliary storage is locked" means another one still runs: lume stop it first.

Share a folder#

lume run macos-tahoe --shared-dir ~/Projects
lume run macos-tahoe --shared-dir ~/Projects:ro

It 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 external

The 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-backup

clone 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 vncdotool
lume 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 --yes

A 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 update
curl -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 nightly

Stable 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 7778
curl http://localhost:7777/lume/vms

The 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 --mcp

The 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#

SymptomFix
Auxiliary storage is lockedAnother lume run owns the VM: lume stop <vm>.
sudo lume cannot find a VMRun as the user who created it.
SSH unavailableCheck lume get <vm> shows running with an IP; unattended VMs use lume / lume.
Sequoia shows an Accessibility step on first bootKnown (#2155); Tahoe is the verified preset.