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.

Lume is a macOS virtualization tool that creates and manages macOS and Linux VMs with near-native performance on Apple Silicon, using Apple’s Virtualization.framework. This tutorial walks through a complete local VM setup: installing Lume, downloading a macOS Tahoe restore image, creating a VM with the unattended preset, starting it, and verifying the guest over SSH.
Prerequisites: An Apple Silicon Mac (M1 or later) running macOS 13 or later, 8 GB of available memory, and at least 50 GB of free disk space. The restore image requires additional download space.

​
Steps

1

Install Lume

Run the one-line installer:
/bin/bash -c "$(curl -fsSL https://cua.ai/lume/install.sh)"
Check the installed version:
lume --version
2

Download the Tahoe restore image

Ask Lume for the latest supported restore image URL, then download it:
IPSW_URL="$(lume ipsw | tail -n 1)"
curl -L "$IPSW_URL" -o ~/Downloads/macos-tahoe.ipsw
The lume ipsw command queries Apple’s catalog and returns a list of verified restore image URLs. tail -n 1 selects the most recent one.
The restore image is large (typically 12–15 GB). Download time depends on your connection speed.
3

Create the VM

Create a new VM using the Tahoe unattended preset:
lume create macos-tahoe \
  --ipsw ~/Downloads/macos-tahoe.ipsw \
  --unattended tahoe
The --unattended tahoe preset prepares the installed guest completely offline. It:
  • Creates the lume user account
  • Enables SSH
  • Configures autologin
  • Disables sleep and screen locking
Creation includes a temporary boot, offline disk setup, and an SSH health check. The VM is stopped when creation finishes.
The Tahoe preset is fully verified end-to-end. The sequoia preset may still open the Accessibility step of Setup Assistant on its first display boot — see the known issue.
4

Run the VM

Start the VM with its display:
lume run macos-tahoe
The default guest credentials are lume / lume. Change the password before using the VM for anything sensitive.
5

Verify over SSH

In another terminal, confirm the guest account is reachable:
lume ssh macos-tahoe 'id -un'
The command prints lume. The SSH connection goes through Lume’s guest networking layer — no port forwarding required.

​
What the unattended preset does

The --unattended option runs a sequence of offline setup steps after the OS is installed:
StepWhat happens
User creationCreates the lume user with password lume
SSH setupEnables and starts sshd
AutologinConfigures automatic login for the lume user
Sleep disabledPrevents the VM from sleeping or locking the screen
SSH health checkVerifies the guest is reachable before reporting success
The VM is fully configured and SSH-accessible before lume create returns.

​
Common Lume commands

# List all VMs
lume list

# Show VM details
lume info macos-tahoe

# Stop a running VM
lume stop macos-tahoe

# Delete a VM
lume delete macos-tahoe

# Run the VM headlessly (no display window)
lume run macos-tahoe --no-display

# Resize the VM disk
lume resize macos-tahoe --disk 100

​
Using Lume with Cua Sandbox

Lume is the local backend for macOS sandboxes in Cua Sandbox. Once Lume is installed, you can create macOS sandboxes from Python:
macos_sandbox.py
from cua import Sandbox, Image

async with Sandbox.ephemeral(Image.macos(), local=True) as sb:
    result = await sb.shell.run("sw_vers")
    print(result.stdout)
    screenshot = await sb.screenshot()

​
Next steps

Create a vanilla Tahoe VM

Lifecycle commands, troubleshooting, and disk resize for macOS VMs.

Serve the Lume API

Expose Lume as a local HTTP API for tools and automation scripts.

Lume CLI reference

Every Lume command, flag, and option explained.

How sandboxes work

Understand how Lume fits into Cua Sandbox as the local macOS VM backend.

Build docs developers (and LLMs) love

Get started for freeTalk to us