FAQ

Common questions about using Lume. For detailed guides, see VM Management and Unattended Setup.

Credentials

What's the default password?

For VMs created with --unattended tahoe:

• Username: lume
• Password: lume

For manually configured VMs, you set credentials during the Setup Assistant.

Storage

Where are VMs stored?

Default location: ~/.lume

Add more locations with:

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

Do VM disks use their full allocated size?

No. macOS uses sparse files—a 50GB disk might only use 20GB on your actual drive, growing as needed.

How do I move a VM to another drive?

Clone it to the new location, then delete the original:

lume clone my-vm my-vm --source-storage default --dest-storage external
lume delete my-vm --storage default

Configuration

Where's the config file?

~/.config/lume/config.yaml (follows XDG Base Directory spec)

View settings with:

lume config get

How do I manage cache settings?

# Check caching status
lume config caching get

# Enable/disable caching
lume config caching set true

# Set cache directory
lume config cache set /path/to/cache

# Clear cache
lume prune

How do I change the display resolution?

By default, VMs use 1024x768. Change it with lume set:

lume set my-vm --display 1920x1080

The VM must be stopped for this to work. After restarting the VM, go to System Settings → Displays, enable Show all resolutions, and select your new resolution. You can also set display resolution during creation:

lume create my-vm --os macos --ipsw latest --display 1920x1080

Limits

How many macOS VMs can I run at once?

Apple's macOS Software License Agreement (section 2.B.iii) limits you to 2 concurrent macOS VMs per physical Mac. This is a licensing restriction, not a technical one—the Virtualization Framework enforces it automatically.

Linux VMs have no such limitation. You can run as many as your hardware supports.

Can I run VMs inside a VM (nested virtualization)?

macOS VMs: No. Apple's Virtualization Framework doesn't support nested virtualization for macOS guests. If you try to run lume create inside a macOS VM, you'll get "Virtualization is not available on this hardware."

Linux VMs: Yes, on macOS 15+. Linux guests can run VMs inside them using KVM or other hypervisors. This is useful for testing Kubernetes, Docker, or other virtualization workloads.

Images

How do I get the latest macOS IPSW URL?

lume ipsw

Where can I get older macOS versions?

Apple only provides the latest IPSW officially. Community archives exist—search "macOS IPSW download" and ensure you get UniversalMac files (for Apple Silicon).

How do I install from a specific IPSW?

Download the IPSW first, then:

lume create my-vm --os macos --ipsw /path/to/downloaded.ipsw

Linux VMs

How do I create a Linux VM?

Linux uses ISO images instead of IPSW. Create the VM, boot with the installer mounted, then run normally:

# Create empty Linux VM
lume create linux-vm --os linux

# First boot: mount installer ISO
lume run linux-vm --mount /path/to/ubuntu.iso

# After installation: run normally
lume run linux-vm

VM Status

What do the different VM statuses mean?

Check VM status with lume ls:

VMs in provisioning status are being created asynchronously. Wait for status to change to stopped before starting them.

Troubleshooting

VM won't start

1. Check if another VM is running: lume ls
2. Stop any running VMs: lume stop <name>
3. Check available disk space
4. If VM shows provisioning, wait for creation to complete
5. Try running with --no-display to see if it's a VNC issue

Can't connect to VM via SSH

1. Ensure SSH is enabled in the VM (System Settings → Sharing → Remote Login)
2. Get the VM's IP: lume get my-vm
3. Try: ssh lume@<ip-address>

For VMs created with --unattended tahoe, SSH is enabled automatically.

lume serve port already in use

Another Lume instance is running. Either use it or kill it:

# Check what's using port 7777
lsof -i :7777

# Kill the process
kill <pid>