VM Management

Once you've created a VM, here's how to manage it.

Quick reference

Task	Command
List VMs	`lume ls`
Get details	`lume get my-vm`
Run	`lume run my-vm`
Run headless	`lume run my-vm --no-display`
Stop	`lume stop my-vm`
Clone	`lume clone my-vm backup`
Delete	`lume delete my-vm`

Run a VM

# Opens VNC window
lume run my-vm

# Headless (for automation)
lume run my-vm --no-display

Mount a host directory that appears in the VM at /Volumes/My Shared Files:

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

Attach USB storage

Mount a disk image as USB storage (macOS 15+ only):

lume run my-vm --usb-storage /path/to/disk.img

Linux VMs

Lume supports Linux VMs using ARM64 ISO images. The workflow differs slightly from macOS.

Create and install

# Create empty VM configured for Linux
lume create ubuntu-vm --os linux --cpu 4 --memory 8GB --disk-size 50GB

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

# After installation: run normally
lume run ubuntu-vm

Complete the installation in the VNC window, shut down, then run without the ISO.

Supported distributions

Any ARM64 Linux distribution works. Download the ARM64 (aarch64) ISO, not x86_64:

Ubuntu - ubuntu.com/download
Debian - debian.org
Fedora - fedoraproject.org

Linux VMs have no licensing restrictions—run as many concurrent instances as your hardware supports. Only macOS VMs are limited to 2 per Mac.

Stop a VM

# Graceful shutdown
lume stop my-vm

# Force stop (immediate)
lume stop my-vm --force

Inspect VMs

# List all VMs with state, CPU, memory, disk
lume ls

# Detailed info for one VM
lume get my-vm

lume get shows state, resource allocation, network config, and display settings.

Change VM settings

Stop the VM before changing settings. Disk size can only increase, not decrease.

# CPU cores
lume set my-vm --cpu 8

# Memory
lume set my-vm --memory 16GB

# Disk (increase only)
lume set my-vm --disk-size 100GB

# Display resolution
lume set my-vm --display 1920x1080

Clone a VM

Cloning creates a full copy—useful for backups or creating variants:

lume clone my-vm my-vm-backup

Clone between storage locations:

lume clone my-vm external-copy \
  --source-storage default \
  --dest-storage external-ssd

Delete a VM

lume delete my-vm

# From specific storage
lume delete my-vm --storage external-ssd

Storage locations

By default, VMs live in ~/.lume. You can add more locations—useful for external drives or separating projects.

Configure storage

# List locations
lume config storage list

# Add a location
lume config storage add external-ssd /Volumes/ExternalSSD/lume

# Set default
lume config storage default external-ssd

# Remove a location
lume config storage remove old-location

Use storage in commands

Most commands accept --storage to target a specific location. You can use either a named location or a direct path:

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

# Or use a direct path
lume create my-vm --os macos --ipsw latest --storage /Volumes/MySSD/vms
lume run my-vm --storage /Volumes/MySSD/vms/my-vm

Without --storage, Lume uses the default location or searches all locations.

Move a VM between locations

Clone to the new location, then delete the original:

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

Image caching

When pulling images from a registry, Lume can cache layers locally for faster future pulls. Caching is disabled by default to save disk space.

# Enable caching
lume config caching set true

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

# View current config
lume config get

# Clear cache
lume prune

Enable caching if you frequently pull the same images or images sharing base layers. With caching disabled, each lume pull downloads everything fresh.

What's next

Automate setup with YAML configurations
Use the HTTP API for programmatic access
See all options in the CLI Reference

Was this page helpful?

VM Management

On this page