https://github.com/trycua/lume
A lightweight CLI and local API server to create, run and manage macOS and Linux virtual machines (VMs) natively on Apple Silicon.
https://github.com/trycua/lume
apple cua lume macos swift virtualization virtualization-framework
Last synced: 2 months ago
JSON representation
A lightweight CLI and local API server to create, run and manage macOS and Linux virtual machines (VMs) natively on Apple Silicon.
- Host: GitHub
- URL: https://github.com/trycua/lume
- Owner: trycua
- License: mit
- Created: 2025-01-31T15:02:49.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-03-14T15:21:02.000Z (2 months ago)
- Last Synced: 2025-03-15T07:51:12.526Z (2 months ago)
- Topics: apple, cua, lume, macos, swift, virtualization, virtualization-framework
- Language: Swift
- Homepage:
- Size: 494 KB
- Stars: 2,162
- Watchers: 9
- Forks: 31
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
![Shows my svg]()
[](#)
[](#)
[](#install)
[](https://discord.com/invite/mVnXXpdE85)
[](#contributors)
**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
```
For a python interface, check out [pylume](https://github.com/trycua/pylume).
## 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 clone 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 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
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)
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)
delete:
--force Force deletion without confirmation
pull:
--registry Container registry URL (default: ghcr.io)
--organization Organization to pull from (default: trycua)
serve:
--port Port to listen on (default: 3000)
```
## Install
```bash
brew tap trycua/lume
brew install lume
```
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).
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 | 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](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.
## Local API Server
`lume` exposes a local HTTP API server that listens on `http://localhost:3000/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.
## Stargazers over time
[](https://starchart.cc/trycua/lume)
## Contributors
