lume

lume command [options]

lume creates, runs, and manages local macOS and Linux virtual machines on Apple Silicon using Apple's Virtualization.framework. It is a single CLI (and optional local API server) aimed at near-native guests without a separate hypervisor stack.Linux guests boot from ARM64 ISO images: create the VM with `--os linux`, run it once with `--mount` pointing at the installer, then run it again without the ISO. macOS guests are created from an IPSW restore image. The `tahoe` unattended preset creates the `lume` user, enables SSH, configures autologin, and disables sleep and screen locking.VMs are stored under `~/.lume` by default. Additional storage locations can be registered with `lume config storage`. Shared host directories appear in the guest at `/Volumes/My Shared Files`. `lume serve` exposes the same operations over HTTP for scripts and tools.Lume is part of the Cua computer-use platform and can back local macOS sandboxes, but the CLI is usable on its own.

create name

Create a VM. --os is `macOS` (default) or `linux`. --cpu, --memory, --disk-size, and --display set resources. macOS guests take --ipsw (path or `latest`) and --unattended (`tahoe` or `sequoia`).

Start a VM. --mount attaches a read-only installer ISO (Linux). --shared-dir path[:ro|:rw] shares a host directory. --display is `native`, `vnc`, or `none`. --detach returns immediately. --vnc disabled starts with no VNC listener.

Open a viewer for a running VM (`--display native` or `vnc`).

Graceful guest shutdown or reboot over SSH (default user and password `lume`).

Immediate process-level stop.

Remove the VM and its disk. --force skips confirmation.

Copy a VM, optionally across --source-storage and --dest-storage.

List VMs. -f, --format is `text` or `json`.

Print state, IP, display, resources, and SSH availability.

Change CPU, memory, disk size (increase only), or display of a stopped VM.

List cached images, pull or push OCI images (default registry `ghcr.io`, organization `trycua`), or drop the cache.

Print the current macOS restore-image URL.

Interactive SSH or a one-shot remote command.

Run unattended macOS setup on an existing VM.

Enable or disable System Integrity Protection from paired Recovery.

Get or set storage locations, image cache, and telemetry (`lume config telemetry disable`).

Start the local VM HTTP API. --port defaults to 7777.

Check or apply updates; persist `stable` or `nightly`.

Help or version, available on every command.

~/.lume

Default VM store. `sudo lume` uses root's home and will not see VMs created as a regular user.

Named extra disk locations (`add`, `list`, `remove`, `default`). Commands also accept --storage name.

Image-layer cache (off by default) and pseudonymous telemetry (on by default). `LUMETELEMETRYENABLED` overrides the persisted telemetry preference for the current process.

Logs for `lume run --detach`.

Requires an Apple Silicon Mac running macOS 13 or later. It does not run on Linux or Intel Macs. Linux installer ISOs must be ARM64 (aarch64), not x86_64.Apple's framework allows at most two concurrent macOS guests. Linux guests have no such cap beyond host RAM, CPU, and disk. Nested virtualization of macOS inside a macOS VM is not supported.Default unattended SSH credentials are `lume` / `lume`. Change the password before using the VM for anything sensitive.Only one `lume run` process can hold a VM's auxiliary storage. A second start reports that auxiliary storage is locked until the first process is stopped.Telemetry is enabled by default (install, release, command, and API-event metadata; not VM names, paths, or guest contents). Disable it with `lume config telemetry disable`.

Lume was open-sourced by trycua (Cua AI, Inc.) in 2025 as a lightweight CLI for macOS and Linux VMs on Apple Silicon. It now lives in the Cua monorepo (`libs/lume`) and is installed with the official script from `https://cua.ai/lume/install.sh`.

lima(1), colima(1), qemu(1), virsh(1), ssh(1), multipass(1)

Source code · Homepage · Documentation