[](#)
[](#)
[](https://discord.com/invite/mVnXXpdE85)
**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
```bash
lume run macos-sequoia-vanilla:latest
```
## Development Environment
If you're working on Lume in the context of the CUA monorepo, we recommend using the dedicated VS Code workspace configuration:
```bash
# Open VS Code workspace from the root of the monorepo
code .vscode/lume.code-workspace
```
This workspace is preconfigured with Swift language support, build tasks, and debug configurations.
## Usage
```bash
lume
Commands:
lume create Create a new macOS or Linux VM
lume run Run a VM
lume ls List all VMs
lume get Get detailed information about a VM
lume set Modify VM configuration
lume stop Stop a running VM
lume delete Delete a VM
lume pull Pull a macOS image from container registry
lume push Push a VM image to a container registry
lume clone Clone an existing VM
lume config Get or set lume configuration
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 Operating system to install (macOS or linux, default: macOS)
--cpu Number of CPU cores (default: 4)
--memory Memory size, e.g., 8GB (default: 4GB)
--disk-size Disk size, e.g., 50GB (default: 40GB)
--display Display resolution (default: 1024x768)
--ipsw Path to IPSW file or 'latest' for macOS VMs
--storage VM storage location to use
run:
--no-display Do not start the VNC client app
--shared-dir Share directory with VM (format: path[:ro|rw])
--mount For Linux VMs only, attach a read-only disk image
--registry Container registry URL (default: ghcr.io)
--organization Organization to pull from (default: trycua)
--vnc-port Port to use for the VNC server (default: 0 for auto-assign)
--recovery-mode For MacOS VMs only, start VM in recovery mode (default: false)
--storage VM storage location to use
set:
--cpu New number of CPU cores (e.g., 4)
--memory New memory size (e.g., 8192MB or 8GB)
--disk-size New disk size (e.g., 40960MB or 40GB)
--display New display resolution in format WIDTHxHEIGHT (e.g., 1024x768)
--storage VM storage location to use
delete:
--force Force deletion without confirmation
--storage VM storage location to use
pull:
--registry Container registry URL (default: ghcr.io)
--organization Organization to pull from (default: trycua)
--storage VM storage location to use
push:
--additional-tags Additional tags to push the same image to
--registry Container registry URL (default: ghcr.io)
--organization Organization/user to push to (default: trycua)
--storage VM storage location to use
--chunk-size-mb Chunk size for disk image upload in MB (default: 512)
--verbose Enable verbose logging
--dry-run Prepare files and show plan without uploading
--reassemble Verify integrity by reassembling chunks (requires --dry-run)
get:
-f, --format Output format (json|text)
--storage VM storage location to use
stop:
--storage VM storage location to use
clone:
--source-storage Source VM storage location
--dest-storage Destination VM storage location
config:
get Get current configuration
storage Manage VM storage locations
add Add a new VM storage location
remove Remove a VM storage location
list List all VM storage locations
default Set the default VM storage location
cache Manage cache settings
get Get current cache directory
set Set cache directory
caching Manage image caching settings
get Show current caching status
set Enable or disable image caching
serve:
--port Port to listen on (default: 7777)
```
## Install
Install with a single command:
```bash
/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:
```bash
/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](https://github.com/trycua/lume/releases), extract it, and install the package manually.
## Prebuilt Images
Pre-built images are available in the registry [ghcr.io/trycua](https://github.com/orgs/trycua/packages).
**Important Note (v0.2.0+):** Images are being re-uploaded with sparse file system optimizations enabled, resulting in significantly lower actual disk usage. Older images (without the `-sparse` suffix) are now **deprecated**. The last version of `lume` fully supporting the non-sparse images was `v0.1.x`. Starting from `v0.2.0`, lume will automatically pull images optimized with sparse file system support.
These images come with an SSH server pre-configured and auto-login enabled.
For the security of your VM, change the default password `lume` immediately after your first login.
| Image | Tag | Description | Logical Size |
|-------|------------|-------------|------|
| `macos-sequoia-vanilla` | `latest`, `15.2` | macOS Sequoia 15.2 image | 20GB |
| `macos-sequoia-xcode` | `latest`, `15.2` | macOS Sequoia 15.2 image with Xcode command line tools | 22GB |
| `macos-sequoia-cua` | `latest`, `15.3` | macOS Sequoia 15.3 image compatible with the Computer interface | 24GB |
| `ubuntu-noble-vanilla` | `latest`, `24.04.1` | [Ubuntu Server for ARM 24.04.1 LTS](https://ubuntu.com/download/server/arm) with Ubuntu Desktop | 20GB |
For additional disk space, resize the VM disk after pulling the image using the `lume set --disk-size ` command. Note that the actual disk space used by sparse images will be much lower than the logical size listed.
## Local API Server
`lume` exposes a local HTTP API server that listens on `http://localhost:7777/lume`, enabling automated management of VMs.
```bash
lume serve
```
For detailed API documentation, please refer to [API Reference](docs/API-Reference.md).
## Docs
- [API Reference](docs/API-Reference.md)
- [Development](docs/Development.md)
- [FAQ](docs/FAQ.md)
## 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](CONTRIBUTING.md).
Join our [Discord community](https://discord.com/invite/mVnXXpdE85) to discuss ideas or get assistance.
## License
lume is open-sourced under the MIT License - see the [LICENSE](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.