lume is a lightweight Command Line Interface and local API server to create, run and manage macOS and Linux virtual machines (VMs) with near-native performance on Apple Silicon, using Apple's Virtualization.Framework.

Run prebuilt macOS images in just 1 step

lume run macos-sequoia-vanilla:latest

For a python interface, check out pylume.

Usage

lume <command>

Commands:
  lume create <name>            Create a new macOS or Linux VM
  lume run <name>               Run a VM
  lume ls                       List all VMs
  lume get <name>               Get detailed information about a VM
  lume set <name>               Modify VM configuration
  lume stop <name>              Stop a running VM
  lume delete <name>            Delete a VM
  lume pull <image>             Pull a macOS image from container registry
  lume clone <name> <new-name>  Clone an existing VM
  lume images                   List available macOS images in local cache
  lume ipsw                     Get the latest macOS restore image URL
  lume prune                    Remove cached images
  lume serve                    Start the API server

Options:
  --help     Show help [boolean]
  --version  Show version number [boolean]

Command Options:
  create:
    --os <os>            Operating system to install (macOS or linux, default: macOS)
    --cpu <cores>        Number of CPU cores (default: 4)
    --memory <size>      Memory size, e.g., 8GB (default: 4GB)
    --disk-size <size>   Disk size, e.g., 50GB (default: 40GB)
    --display <res>      Display resolution (default: 1024x768)
    --ipsw <path>        Path to IPSW file or 'latest' for macOS VMs

  run:
    --no-display         Do not start the VNC client app
    --shared-dir <dir>   Share directory with VM (format: path[:ro|rw])
    --mount <path>       For Linux VMs only, attach a read-only disk image

  set:
    --cpu <cores>        New number of CPU cores
    --memory <size>      New memory size
    --disk-size <size>   New disk size

  delete:
    --force              Force deletion without confirmation

  pull:
    --registry <url>     Container registry URL (default: ghcr.io)
    --organization <org> Organization to pull from (default: trycua)

  serve:
    --port <port>        Port to listen on (default: 3000)

Install

brew tap trycua/lume
brew install lume

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

Prebuilt Images

Pre-built images are available on ghcr.io/trycua. These images come with an SSH server pre-configured and auto-login enabled.

Image	Tag	Description	Size
macos-sequoia-vanilla	latest, 15.2	macOS Sequoia 15.2	40GB
macos-sequoia-xcode	latest, 15.2	macOS Sequoia 15.2 with Xcode command line tools	50GB
ubuntu-noble-vanilla	latest, 24.04.1	Ubuntu Server for ARM 24.04.1 LTS with Ubuntu Desktop	20GB

For additional disk space, resize the VM disk after pulling the image using the lume set <name> --disk-size <size> command.

Local API Server

lume exposes a local HTTP API server that listens on http://localhost:3000/lume, enabling automated management of VMs.

lume serve

For detailed API documentation, please refer to API Reference.

Docs

• API Reference
• Development
• FAQ

Contributing

We welcome and greatly appreciate contributions to lume! Whether you're improving documentation, adding new features, fixing bugs, or adding new VM images, your efforts help make lume better for everyone. For detailed instructions on how to contribute, please refer to our Contributing Guidelines.

Join our Discord community to discuss ideas or get assistance.

License

lume is open-sourced under the MIT License - see the LICENSE file for details.

Trademarks

Apple, macOS, and Apple Silicon are trademarks of Apple Inc. Ubuntu and Canonical are registered trademarks of Canonical Ltd. This project is not affiliated with, endorsed by, or sponsored by Apple Inc. or Canonical Ltd.

Stargazers over time