What is Lume? | CuaLumeDocsGuideExamplesReferenceCuaCua-BenchLumeGuideGetting StartedWhat is Lume?InstallationQuickstartComparisonFAQFundamentalsAdvancedExamplesReferenceWhat is Lume?LumeGuideGetting StartedWhat is Lume?Introduction to Lume - the macOS VM CLI and frameworkLume is a VM runtime for building AI agents, running CI/CD pipelines, and automating macOS. It uses Apple's native Virtualization Framework to run macOS and Linux VMs at near-native speed on Apple Silicon.
MIT LicenseLume is open-source and MIT licensed. If you find it useful, we'd appreciate a star on GitHub!
Cloud macOS SandboxesWe're piloting a managed service for customers who want to run cloud macOS sandboxes for CI/CD and agent workloads. Book a demo if you're interested.
lume create test-vm --os macos --ipsw latest
lume run test-vm
A single binary with an HTTP API. Create a VM, run it headlessly, control it programmatically.
Architecture

You can use Lume directly via CLI, or run lume serve to expose an HTTP API for programmatic access. The Computer SDK uses this API to automate macOS interactions.
How it works
Lume is a thin layer over Apple's Virtualization Framework, which provides hardware-accelerated virtualization on Apple Silicon. This gives you:

Native speed — CPU instructions execute directly via hardware virtualization
Paravirtualized graphics — Basic GPU support via Apple's virtualization layer (limited to GPU Family 5)
Efficient storage — Sparse disk files only consume actual usage, not allocated size
Rosetta 2 support — Run x86 Linux binaries in ARM Linux VMs
Automated golden images — Go from IPSW to fully configured macOS VM without manual intervention
Registry support — Pull and push VM images from GHCR or GCS registries

When to use Lume
Testing across macOS versions — Spin up a VM with a specific macOS version, test your software, tear it down. No need to maintain multiple physical machines.
Automating macOS tasks — Combine Lume with Unattended Setup to create pre-configured VMs. The setup automation uses VNC and OCR to click through the Setup Assistant without manual intervention.
Running CI/CD locally — Test your macOS builds in isolated VMs before pushing to remote CI. The --no-display flag runs VMs headlessly.
Sandboxing risky operations — Need to test untrusted software or destructive scripts? Run them in a VM, then delete it. Clone a known-good VM to reset to a clean state instantly.
Building AI agents — Lume powers the Cua Computer SDK, providing VMs that AI models can interact with through screenshots and input simulation.
Used by AnthropicApple's Virtualization Framework—the same technology Lume is built on—powers Claude Cowork, Anthropic's sandboxed environment for Claude Code. It downloads a Linux root filesystem and boots it in an isolated VM where Claude can safely execute commands without access to your broader system.
What Lume doesn't do
Lume requires Apple Silicon—it won't work on Intel Macs or other platforms.
Get started
Ready to try it? Install Lume and create your first VM in the Quickstart.Was this page helpful?YesNoSDK ReferenceSession interface for interacting with desktop environmentsInstallationInstall Lume on your MacOn this pageArchitectureHow it worksWhen to use LumeWhat Lume doesn't doGet startedCopy as markdownEdit on GitHubOpen in ChatGPTOpen in Claude© 2026 Cua AI, Inc.PrivacyCookies

Lume is a command-line interface (CLI) and framework designed to facilitate the creation and management of virtual machines (VMs) running macOS and Linux on Apple Silicon devices. Built upon Apple’s native Virtualization Framework, Lume leverages hardware-accelerated virtualization to deliver near-native performance for tasks such as building AI agents, executing CI/CD pipelines, and automating macOS workflows. The tool operates as a thin layer over Apple’s virtualization technology, enabling users to spin up VMs with minimal overhead while maintaining compatibility with both macOS and Linux environments. Lume’s primary value proposition lies in its ability to abstract the complexity of virtualization, offering a streamlined interface for developers and system administrators to manage VMs programmatically or through a simple CLI. Its open-source nature, governed by the MIT License, allows for community contributions and flexibility in deployment, with the project hosted on GitHub. Additionally, Lume provides a managed cloud service for customers seeking to run macOS sandboxes in the cloud, which is particularly useful for CI/CD and agent-based workloads. This service, currently in a pilot phase, enables users to test and deploy applications within isolated environments without the need for physical hardware. The core functionality of Lume is encapsulated in a single binary, which includes an HTTP API for programmatic control, allowing integration with other tools and automation workflows. For instance, users can create a VM using the command `lume create test-vm --os macos --ipsw latest`, followed by running it with `lume run test-vm`. This simplicity extends to the tool’s architecture, which supports both direct CLI interaction and a server mode (`lume serve`) for API-based access. The Computer SDK, which is built on Lume’s API, demonstrates its utility in automating macOS interactions, such as simulating user input or capturing screenshots to interface with AI models.

The underlying architecture of Lume is rooted in Apple’s Virtualization Framework, which provides hardware-level virtualization capabilities optimized for Apple Silicon. This integration enables Lume to deliver native-speed performance by executing CPU instructions directly through the hardware, minimizing the overhead typically associated with virtualization. Furthermore, Lume supports paravirtualized graphics, offering basic GPU acceleration for macOS VMs via Apple’s virtualization layer. However, this support is limited to GPU Family 5, which may restrict advanced graphics workloads. Storage efficiency is another key feature of Lume, as it employs sparse disk files that only consume the actual storage space used by a VM rather than the allocated size, reducing resource consumption. The tool also incorporates Rosetta 2, which allows ARM-based Linux VMs to run x86-compatible binaries natively, bridging the gap between different architectures. This capability is particularly valuable for developers who need to test applications across multiple platforms without maintaining separate hardware setups. Automation is a central theme in Lume’s design, with features like automated golden images that streamline the process of provisioning macOS VMs. Users can convert an IPSW file (Apple’s firmware image) into a fully configured VM without manual intervention, significantly reducing setup time. Additionally, Lume supports registry integration with services like GitHub Container Registry (GHCR) and Google Cloud Storage (GCS), enabling users to pull and push VM images as part of a broader DevOps pipeline. These features collectively position Lume as a versatile tool for developers seeking to balance performance, flexibility, and automation in their workflows.

The use cases for Lume span a wide range of applications, from software testing to AI development. One of its primary applications is cross-version testing of macOS software. By creating VMs with specific macOS versions, developers can test their applications in isolated environments without the need for multiple physical machines. This capability is especially useful for ensuring compatibility across different macOS releases, which can be critical for enterprise software or applications targeting a broad user base. Another significant use case is the automation of macOS tasks through integration with Unattended Setup, a tool that automates the configuration of macOS VMs. By leveraging VNC and OCR (optical character recognition), Unattended Setup can navigate the macOS setup assistant without human intervention, enabling fully automated deployment of pre-configured VMs. This is particularly beneficial for CI/CD pipelines, where rapid provisioning of test environments is essential. Lume also supports headless VM operation via the `--no-display` flag, allowing CI/CD processes to run without requiring a graphical interface. This feature is crucial for environments where resources are constrained or where automation must occur in the background. Additionally, Lume’s sandboxing capabilities make it suitable for testing untrusted software or executing potentially destructive scripts in a controlled environment. Users can create VMs from known-good snapshots, ensuring that any harmful activity is contained and easily reversible. This makes Lume an attractive option for security testing or experimental development scenarios where isolation is paramount.

For AI developers, Lume serves as a foundational component of the Cua Computer SDK, which enables AI models to interact with macOS environments through simulated inputs and outputs. By providing a VM infrastructure that can be controlled programmatically, Lume allows AI agents to perform tasks such as analyzing screenshots, executing commands, or simulating user interactions. This integration is particularly relevant for projects like Claude Cowork, a sandboxed environment developed by Anthropic that uses Apple’s Virtualization Framework to run Linux root filesystems in isolated VMs. The collaboration between Lume and Anthropic highlights the tool’s role in enabling secure, scalable AI workflows that leverage virtualization for both performance and isolation. However, it is important to note that Lume’s capabilities are constrained by its dependency on Apple Silicon hardware. Unlike traditional virtualization solutions, which can operate on a variety of platforms, Lume is incompatible with Intel-based Macs or other architectures. This limitation restricts its use cases to environments equipped with Apple Silicon chips, such as M1 or M2 MacBooks and Mac Minis. Despite this restriction, the tool’s performance advantages on Apple Silicon make it a compelling choice for developers working within that ecosystem.

The Lume project also emphasizes ease of adoption, with a straightforward installation process and clear documentation to guide users through its features. The Quickstart section of the project’s documentation provides step-by-step instructions for installing Lume and creating a test VM, making it accessible even to those new to virtualization. The tool’s reliance on a single binary simplifies deployment, as it eliminates the need for complex setup procedures or multiple dependencies. Furthermore, Lume’s HTTP API enables integration with existing systems, allowing developers to build custom workflows that leverage its capabilities. For example, the Computer SDK uses this API to automate macOS interactions, demonstrating how Lume can be extended to support specialized applications. The project’s documentation also includes a comprehensive reference for the Session interface, which allows users to interact with desktop environments programmatically. This level of detail ensures that developers can customize Lume’s functionality to suit their specific needs, whether for testing, automation, or AI development.

Despite its strengths, Lume is not without limitations. Its exclusive support for Apple Silicon hardware means that users of older Intel-based Macs or non-Apple platforms cannot benefit from its features. This restriction may limit its adoption in environments where hardware compatibility is a concern. Additionally, while Lume’s paravirtualized graphics support is sufficient for basic tasks, it may not meet the demands of applications requiring advanced GPU acceleration. Developers relying on high-performance graphics or machine learning workloads may need to seek alternative solutions for such tasks. However, these limitations are contextual and do not detract from Lume’s core value proposition as a lightweight, high-performance virtualization tool for Apple Silicon platforms. The project’s ongoing development and community support suggest that future updates may address some of these constraints, further expanding its utility.

In conclusion, Lume represents a significant advancement in virtualization for Apple Silicon devices, offering a powerful yet accessible solution for developers and system administrators. Its integration with Apple’s Virtualization Framework ensures near-native performance, while its focus on automation and ease of use makes it well-suited for a wide range of applications. From testing macOS versions to powering AI agents, Lume’s versatility is evident in its design and functionality. The tool’s open-source model and managed cloud service options further enhance its appeal, providing flexibility for both individual users and enterprise teams. While its dependency on Apple Silicon hardware may limit its reach, Lume’s performance advantages and robust feature set position it as a valuable asset for those working within the Apple ecosystem. As virtualization continues to evolve, Lume’s contributions underscore the potential of hardware-accelerated solutions in modern software development and AI workflows.