Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/trycua/cua/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers the full VM lifecycle in Lume — from creating a macOS or Linux guest to running, inspecting, cloning, and deleting it. All commands assume Lume is already installed. If it isn’t, see the Install guide.

​
Create a macOS VM

Lume creates macOS VMs from an Apple restore image (IPSW). The --unattended flag applies an offline preset that configures the guest account, enables SSH, sets up autologin, and disables sleep — no GUI interaction needed.
1

Get the IPSW URL and download the image

Use lume ipsw to get the latest supported restore image URL, then download it:
curl -L "$(lume ipsw | tail -n 1)" -o ~/Downloads/macos-tahoe.ipsw
This may take a while — a typical IPSW is around 14–16 GB.
2

Create the VM

Create a new VM named macos-tahoe using the tahoe unattended preset:
lume create macos-tahoe \
  --ipsw ~/Downloads/macos-tahoe.ipsw \
  --unattended tahoe
Lume installs macOS, applies the offline preset, boots the VM once to verify SSH, and then stops it. The tahoe preset:
  • Creates the lume user account
  • Enables SSH (Remote Login)
  • Configures autologin for the lume user
  • Disables sleep and screen locking
Default SSH credentials are lume / lume.
To use Sequoia instead, replace tahoe with sequoia in --unattended and choose a matching IPSW. Note that Sequoia may show the Accessibility step of Setup Assistant on its first display boot (#2155).
3

Run the VM

Start the VM with the native viewer:
lume run macos-tahoe
To start headlessly in the background:
lume run macos-tahoe --detach

​
Create a Linux VM

Pull a pre-built Ubuntu image from the OCI registry and run it immediately: 
lume pull ghcr.io/trycua/ubuntu-24.04-arm64:latest
lume run ubuntu-24.04-arm64
The pulled image name defaults to the image name without the registry prefix. Run lume ls to confirm the VM name before running it.

​
List and inspect VMs

List all VMs and their current state: 
lume ls
Get full details for one VM — state, IP address, display session, resources, and SSH availability: 
lume get macos-tahoe

​
Run, attach, and stop VMs

lume run macos-tahoe
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 lume attach. To stop a VM: 
lume shutdown macos-tahoe
Only one lume run process can hold a VM’s auxiliary storage at a time. If you see an “auxiliary storage is locked” error, stop the existing process before starting the VM again.

​
SSH into a VM

Connect interactively to a running VM using the default lume credentials: 
lume ssh macos-tahoe
Run a one-off command without opening an interactive shell: 
lume ssh macos-tahoe 'sw_vers; id -un'
Use --user and --password for non-default accounts: 
lume ssh macos-tahoe --user admin --password mypassword 'whoami'

​
Share a host directory

Pass a host path when starting the VM. It appears inside the guest at /Volumes/My Shared Files: 
lume run macos-tahoe --shared-dir ~/Projects
For a read-only mount: 
lume run macos-tahoe --shared-dir ~/Projects:ro
In the native viewer, use the Share Folder toolbar button to add a directory while the VM is already running — no guest restart required.

​
Copy files into a VM

Drop files or folders from Finder onto the native VM window. Lume transfers them over SSH to /Users/lume/Desktop. File drop requires SSH to be available for the lume account and works host-to-guest only.

​
Store VMs on another volume

Move VMs to an external drive by adding a named storage location: 
lume config storage add external /Volumes/External/lume
lume config storage list
lume config storage default external
Create or run a VM in a specific storage location: 
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. Always run Lume as the user who owns that directory. Running sudo lume uses a different home directory and cannot see your VMs.

​
Clone a VM

Clone a VM before making changes or to create a reusable baseline: 
lume clone macos-tahoe macos-tahoe-backup
lume clone copies both disk.img and nvram.bin together. Do not copy these files individually — the signed boot policy and anti-replay state belong to the paired VM state.

​
Delete a VM

Remove a VM and its disk permanently: 
lume delete macos-tahoe-backup
Deletion is permanent. Clone the VM first if you might need it again. macOS VM disks can be sparse, so the configured capacity and actual host disk usage may differ.

​
Resource configuration

Adjust CPU cores, memory, and display resolution when the VM is stopped: 
lume set macos-tahoe --cpu 8 --memory 16GB --display 1920x1080
To expand disk size, see Advanced → Expanding VM disk size.

Build docs developers (and LLMs) love

Get started for freeTalk to us