Quickstart

In under 5 minutes, you'll have a macOS VM running on your Mac.

Get the macOS restore image

Before creating a VM, you need a macOS restore image (IPSW). You have two options:

Option 1: Download manually (recommended)

Get the download URL and download the IPSW file yourself:

# Get the latest IPSW download URL
lume ipsw
# Output: https://updates.cdn-apple.com/...

# Download it (using curl, wget, or your browser)
curl -L -o ~/Downloads/macos.ipsw "$(lume ipsw)"

# Create the VM with the downloaded file
lume create my-vm --os macos --ipsw ~/Downloads/macos.ipsw

This approach is better for slower connections since you can resume downloads and reuse the IPSW for multiple VMs.

Option 2: Let Lume download it

Use --ipsw latest and Lume will download the restore image automatically:

lume create my-vm --os macos --ipsw latest

Configure VM storage location (optional)

By default, VMs are stored in ~/.lume. You can configure custom storage locations before creating VMs—useful for external drives or organizing VMs by project.

# Add an external drive as a storage location
lume config storage add external /Volumes/MySSD/lume

# Set it as the default for new VMs
lume config storage default external

# View all configured storage locations
lume config storage list

When creating a VM, specify which storage to use:

# Use a named storage location
lume create my-vm --os macos --ipsw latest --storage external

# Or use a direct path
lume create my-vm --os macos --ipsw latest --storage /path/to/vm/directory

Create a Linux VM

Lume also supports Linux VMs using ISO images:

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

# First boot: mount the installer ISO
lume run ubuntu-vm --mount ~/Downloads/ubuntu-24.04-live-server-arm64.iso

# After installation completes, run normally
lume run ubuntu-vm

Run your VM

lume run my-vm

A VNC window opens. For macOS VMs, you'll see the Setup Assistant—complete it manually or use Unattended Setup to automate it.

Create a VM with custom resources

By default, Lume creates VMs with 4 CPU cores, 8GB memory, and a 50GB disk. Override any of these:

lume create dev-vm --os macos --ipsw latest \
  --cpu 8 \
  --memory 16GB \
  --disk-size 100GB

Change display resolution

By default, VMs use a 1024x768 display resolution. You can change it with lume set:

lume set my-vm --display 1920x1080

The change takes effect on the next VM start. After starting the VM, go to System Settings → Displays, enable Show all resolutions, and select your new resolution. Common resolutions:

Automate the Setup Assistant

Skip manual setup entirely with the --unattended flag:

lume create my-vm --os macos --ipsw latest --unattended tahoe

The tahoe preset runs through the Setup Assistant automatically, creating a user lume with password lume and enabling SSH. This takes 10-15 minutes but requires no interaction.

For custom configurations, see Unattended Setup.

Run a VM

# With display (VNC window opens)
lume run my-vm

# Headless (for automation, CI/CD)
lume run my-vm --no-display

# Run in background (doesn't block terminal)
lume run my-vm > /dev/null 2>&1 &

When running headless or in background, connect via SSH (if enabled) or VNC client. Use lume ls to see running VMs and their connection details.

Common operations

# List all VMs
lume ls

# Get details about a VM
lume get my-vm

# Stop a running VM
lume stop my-vm

# Clone a VM
lume clone my-vm my-vm-backup

# Delete a VM
lume delete my-vm

Share files with your VM

Mount a host directory inside the VM:

lume run my-vm --shared-dir ~/Projects

Inside the VM, find your files at /Volumes/My Shared Files.

What's next

Now that you have a VM running, you can:

• Learn more VM operations like modifying resources and managing storage locations
• Set up automated configuration with custom YAML files
• Integrate with your tools via the HTTP API
• Connect AI agents like Claude Desktop via MCP