Lume CLI Reference

Lume is a lightweight Command Line Interface and local API server for creating, running and managing macOS and Linux virtual machines with near-native performance on Apple Silicon, using Apple's Virtualization.Framework.

Quick Start

Install and run a prebuilt macOS VM in two commands:

# Install Lume
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
# Pull & start a macOS image
lume run macos-sequoia-vanilla:latest

Security Note: All prebuilt images use the default password lume. Change this immediately after your first login using the passwd command.

System Requirements:

Apple Silicon Mac (M1, M2, M3, etc.)
macOS 13.0 or later
At least 8GB of RAM (16GB recommended)
At least 50GB of free disk space

Install

Install with a single command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"

By default, Lume is installed as a background service that starts automatically on login. If you prefer to start the Lume API service manually when needed, you can use the --no-background-service option:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh) --no-background-service"

Note: With this option, you'll need to manually start the Lume API service by running lume serve in your terminal whenever you need to use tools or libraries that rely on the Lume API (such as the Computer-Use Agent).

You can also download the lume.pkg.tar.gz archive from the latest release, extract it, and install the package manually.

Using Lume

Once installed, you can start using Lume with these common workflows:

Run a Prebuilt VM

# Run a macOS Sequoia VM
lume run macos-sequoia-vanilla:latest

# Run an Ubuntu VM
lume run ubuntu-noble-vanilla:latest

We provide prebuilt VM images in our ghcr registry.

Create a Custom VM

# Create a new macOS VM
lume create my-macos-vm --cpu 4 --memory 8GB --disk-size 50GB

# Create a Linux VM
lume create my-linux-vm --os linux --cpu 2 --memory 4GB

Disk Space: The actual disk space used by sparse images will be much lower than the logical size listed. You can resize VM disks after creation using lume set <name> --disk-size <size>.