Limits and VM states

Host requirements, VM states, storage behavior, and common Lume failures.

This page records constraints that affect Lume workflows. Use the CLI reference for command syntax.

Host requirements#

Lume runs on Apple Silicon Macs.
macOS 13 or later is required.
Lume needs at least 8GB of available memory. 16GB is a better starting point for a guest with 8GB allocated.
Leave at least 50GB of free disk space for a macOS guest and its restore image.

macOS VM concurrency#

Apple's Virtualization framework allows Lume to run up to two macOS guests on a host. Memory, disk, and CPU capacity can reduce the practical limit.

VM states#

lume ls can report these states:

State	Meaning
`stopped`	The VM is ready to start.
`running`	The VM is booted and has a live virtualization session.
`provisioning`	Lume is creating the VM or completing an asynchronous operation.
`provisioning (stale)`	A provisioning marker remains after its operation stopped unexpectedly.

Wait for a provisioning operation to finish before running the VM. If a VM is stale, inspect the Lume logs and remove the incomplete VM before recreating it.

Common failures#

Auxiliary storage is locked#

Only one process can run a VM at a time. Check the VM list and stop the process that owns the VM before retrying:

lume ls
lume stop macos-tahoe

`sudo lume` cannot find a VM#

Lume stores VMs under the current user's home directory by default. Running with sudo changes HOME, so the root process looks in a different VM store. Run Lume as the account that created the VM.

SSH is unavailable#

VMs created with --unattended tahoe enable SSH and use lume / lume for the initial account. Check that the VM is running, then inspect its details:

lume run macos-tahoe --no-display
lume get macos-tahoe
lume ssh macos-tahoe 'id -un'

SIP automation#

lume sip supports stopped macOS VMs only.
The VM must have a working administrator account and Remote Login enabled.
The optional vncdotool package provides Recovery VNC input.
Recovery input accepts administrator passwords made from lowercase ASCII letters, digits, and hyphens.
The account named by --admin-user must match the Recovery password prompt.
Tahoe is the currently verified Recovery workflow.
The command leaves the VM stopped after a successful policy change.
If Recovery does not halt during its grace period, Lume stops that exact run process and requires a normal-boot csrutil status verification.
Customized SIP policies are rejected because they do not have one canonical enabled or disabled state.

Disk allocation#

macOS VM disks use sparse files. The configured disk capacity describes the guest's logical disk. The host allocation grows as the guest writes data.

Disk resizing#

Disk resizing is increase-only and requires a stopped VM.
macOS resizing supports the standard Lume layout: ISC, main APFS, then paired RecoveryOS.
FileVault-encrypted macOS guests are unsupported.
The host must run the same or a newer macOS version than the guest.
The default rollback copy requires enough host capacity for the allocated RecoveryOS data and copy-on-write metadata.
The first macOS increase must leave enough room to relocate RecoveryOS without overlapping its old location. Lume reports the minimum accepted total size.
Linux resizing increases the image only. Grow the partition and filesystem in the guest.