Lume is Cua’s open-source VM management layer for Apple Silicon Macs. It uses Apple’s nativeDocumentation 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.
Virtualization.framework to create and run macOS and Linux guests at near-native performance — no emulation, no third-party hypervisor. Lume powers the local VM substrate behind Cua sandboxes and can be used as a standalone tool for any workflow that needs isolated macOS or Linux environments.
How Lume works
Lume wrapsVirtualization.framework with a developer-friendly CLI and a local HTTP API. Every VM gets its own disk image, NVRAM state, and virtual hardware configuration. macOS guests run with a paravirtualized GPU bridge, shared directory support, and bidirectional clipboard sync. Linux guests run with virtio block storage and can attach additional disk images.
The unattended setup feature installs macOS from a standard Apple restore image (IPSW) and prepares the guest account, SSH, autologin, and power settings offline — no GUI automation required.
Supported guest operating systems
| Guest OS | Notes |
|---|---|
| macOS Sequoia | Unattended preset available; first-display Accessibility step may appear (see #2155) |
| macOS Tahoe | Fully verified unattended preset; recommended for new VMs |
| Ubuntu 24.04 (Linux, arm64) | Pull from ghcr.io/trycua/ubuntu-24.04-arm64:latest |
Requirements
- Apple Silicon Mac (M1, M2, M3, or later)
- macOS 14 Sonoma or later on the host
- At least 8 GB of RAM (16 GB recommended)
- At least 50 GB of free disk space
Key capabilities
Create & run VMs
Create macOS VMs from an IPSW or pull Linux images from an OCI registry, then run them with a native viewer or headlessly.
Manage the lifecycle
List, inspect, clone, stop, and delete VMs. Share host directories, move VMs to external storage, and expand disks without data loss.
HTTP API server
Run
lume serve to expose all VM management operations over a local HTTP API so scripts and services can automate them.MCP server
Run
lume serve --mcp to expose VM tools to any Model Context Protocol–compatible AI client for fully automated VM workflows.lumier: Docker-compatible interface
lumier is a Docker image that wraps Lume. It starts a macOS or Linux VM from inside a container, serves the display over noVNC on port 8006, and exposes the Lume HTTP API on the host. Use lumier when you want to integrate Lume VMs into a container-based workflow or CI system.Telemetry
Lume records pseudonymous installation, release, command, and API-event metadata by default. It does not collect prompts, VM names, file paths, command arguments, or VM contents. Telemetry can be disabled at any time:Next steps
Install Lume
Install Lume on your Apple Silicon Mac with a single command.
Manage VMs
Create, run, inspect, and remove macOS and Linux VMs.
Advanced topics
Expand disks, enable GPU passthrough, configure SIP, and run the API server.
CLI Reference
Browse every Lume command, option, and flag.