Manage local Lume VMs

Run, inspect, clone, share files with, and remove local Lume VMs.

Use this guide after you have created a VM and need the everyday lifecycle and storage commands.

Inspect VMs#

List all VMs:

lume ls

Get details for one VM:

lume get macos-tahoe

The details include the VM state, IP address, display session, resources, and SSH availability when the VM is running.

Run, attach to, and stop a VM#

Run Tahoe with the low-latency native viewer. VNC remains available for automation and remote access, and the owning process stays attached to the terminal:

lume run macos-tahoe

Use --detach to run it in the background without opening a viewer. Lume prints its PID and writes logs to ~/Library/Logs/lume/macos-tahoe.log by default:

lume run macos-tahoe --detach

VNC remains active in the background. From another terminal, attach the preferred viewer; Lume uses its native viewer when the owning process supports live attachment and otherwise falls back to VNC:

lume attach macos-tahoe

Select a viewer explicitly when needed:

lume attach macos-tahoe --display native
lume attach macos-tahoe --display vnc

Select Screen Sharing or suppress the startup viewer explicitly when needed:

lume run macos-tahoe --display vnc
lume run macos-tahoe --display none

Closing the native window only hides it; it does not stop the guest. Reopen it from Lume's Dock icon, Window → Show VM Window, or another lume attach command. The older --no-display flag remains an alias for --display none.

Run without a VNC server#

--display chooses a local viewer, but Lume still starts a VNC server in every display mode so automation and lume attach --display vnc keep working. Opt out of the VNC server entirely with --vnc disabled:

lume run macos-tahoe --display none --vnc disabled

That run binds no VNC port, writes no VNC password to the guest, and reports "vncUrl": null in lume get and lume list. lume stop, lume delete, and running status still work across processes, including for --detach runs.

--vnc disabled is rejected together with --display vnc, --vnc-port, or --vnc-password, since each of those needs a VNC server. Guest clipboard shortcuts in the native viewer travel over VNC, so they are unavailable in a VNC-disabled run.

Copy files into a native guest#

Drop one or more files or folders from Finder onto the native VM screen. Lume shows the transfer status while recursively copying the items over SSH to /Users/lume/Desktop.

File drop is available only in the native viewer and transfers from host to guest. SSH for the default lume guest account must be available. Lume rejects the entire drop rather than overwriting an existing Desktop item; items in the same drop must also have distinct names.

Gracefully restart or shut down a guest over SSH:

lume restart macos-tahoe
lume shutdown macos-tahoe

Keep stop for an immediate process-level stop:

lume stop macos-tahoe

Only one lume run process can hold a VM's auxiliary storage at a time. If a second process reports that auxiliary storage is locked, stop the existing process before starting the VM again.

Pass a host directory when you run the VM:

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

The directory appears in the guest at /Volumes/My Shared Files. In the native viewer, Share Folder can also add a directory while the guest is running, including the first folder added to a VM that started without shared folders; no guest restart or remount is needed. Folders added from the toolbar last for that run only. Use a read-only mount when the guest only needs to read the files:

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

Store VMs on another volume#

Add a named storage location and make it the default:

lume config storage add external /Volumes/External/lume
lume config storage list
lume config storage default external

Commands also accept a storage name directly:

lume create macos-tahoe \
  --ipsw ~/Downloads/macos-tahoe.ipsw \
  --unattended tahoe \
  --storage external
lume run macos-tahoe --storage external

The default VM directory is ~/.lume. Run Lume as the same user that owns this directory; sudo lume uses a different home directory and cannot see those VMs.

Expand a VM disk#

Follow Expand a VM disk to preview the change, grow the disk, and verify the guest capacity.

Clone and remove VMs#

Clone a VM before making changes or using it as a reusable starting point:

lume clone macos-tahoe macos-tahoe-backup

Remove a VM and its disk when you no longer need it:

lume delete macos-tahoe-backup

macOS VM disks can be sparse. The configured capacity and the host space used by the disk can therefore differ.

To disable or enable System Integrity Protection, follow Change SIP on a macOS VM.