# How Lume Uses Apple's Virtualization Framework for Near-Native macOS Performance

> Discover how Lume uses Apple's Virtualization Framework to achieve near-native macOS performance on Apple Silicon. Run macOS VMs directly with hardware acceleration and paravirtualized I/O.

- Repository: [Cua/cua](https://github.com/trycua/cua)
- Tags: how-to-guide
- Published: 2026-04-27

---

**Lume leverages Apple's Virtualization Framework to run macOS VMs directly on Apple Silicon hypervisors, bypassing emulation overhead through hardware acceleration and paravirtualized I/O devices.**

Lume is a lightweight Swift runtime within the [trycua/cua](https://github.com/trycua/cua) repository that transforms Apple's low-level `Virtualization` module into a convenient CLI (`lume`) and HTTP service. By interfacing directly with the Apple Silicon hypervisor, Lume enables macOS virtual machines to execute with near-native instruction throughput, serving as the foundational virtualization layer for the CUA Computer SDK.

## Core Architecture

Lume organizes its virtualization stack into four distinct layers that abstract Apple's framework into a developer-friendly API.

The **CLI / HTTP API** layer in [`libs/lume/src/LumeController.swift`](https://github.com/trycua/cua/blob/main/libs/lume/src/LumeController.swift) parses user commands and exposes REST endpoints that the CUA SDK consumes to orchestrate VM lifecycles. 

The **VM Model** layer defines abstract representations of virtual machines through [`libs/lume/src/VM/VM.swift`](https://github.com/trycua/cua/blob/main/libs/lume/src/VM/VM.swift), with concrete implementations in [`DarwinVM.swift`](https://github.com/trycua/cua/blob/main/DarwinVM.swift) (macOS) and [`LinuxVM.swift`](https://github.com/trycua/cua/blob/main/LinuxVM.swift) (Linux) providing platform-specific behavior.

The **Virtualization Service** layer in [`libs/lume/src/Virtualization/VMVirtualizationService.swift`](https://github.com/trycua/cua/blob/main/libs/lume/src/Virtualization/VMVirtualizationService.swift) wraps `VZVirtualMachine` and defines the `VMVirtualizationService` protocol and `BaseVirtualizationService` class for configuration management.

The **Darwin-Specific Service** handles macOS particulars by building `VZMacPlatformConfiguration` instances, managing auxiliary storage for NVRAM, and invoking `VZMacOSInstaller` for system provisioning.

## Hardware-Accelerated Configuration

Lume constructs VM configurations through `DarwinVirtualizationService.createConfiguration`, which generates a `VZVirtualMachineConfiguration` populated with hardware-accelerated devices.

### CPU and Memory Allocation

The configuration sets processor cores via `vzConfig.cpuCount` and allocates RAM through `vzConfig.memorySize`. These values pass directly to the hypervisor without translation layers, ensuring the guest OS runs native Apple Silicon instructions.

### Platform Identity

Each macOS VM requires a validated hardware model and unique machine identifier. Lume extracts the `hardwareModel` from the IPSW image and constructs a `VZMacHardwareModel`, while generating a random `VZMacMachineIdentifier`. These are bound to a `VZMacPlatformConfiguration` along with `VZMacAuxiliaryStorage` pointing to the NVRAM file path.

### Paravirtualized Graphics and Display

Graphics acceleration uses `VZMacGraphicsDeviceConfiguration`. When a host screen is available, Lume creates a `VZMacGraphicsDisplayConfiguration` that maps the VM framebuffer directly to the host's compositor, enabling high-speed screenshot capture critical for CUA's screen-based observations.

```swift
let display = VMDisplayResolution(string: config.display)!   
let graphics = VZMacGraphicsDeviceConfiguration()
if let hostScreen = NSScreen.main {
    let vmSize = NSSize(width: display.width, height: display.height)
    graphics.displays = [
        VZMacGraphicsDisplayConfiguration(for: hostScreen, sizeInPoints: vmSize)
    ]
} else {
    graphics.displays = [
        VZMacGraphicsDisplayConfiguration(
            widthInPixels: display.width,
            heightInPixels: display.height,
            pixelsPerInch: 220
        )
    ]
}
vzConfig.graphicsDevices = [graphics]

```

### Storage and Networking

Primary storage attaches as a `VZVirtioBlockDeviceConfiguration` backed by sparse disk images, bypassing emulation overhead through paravirtualized I/O. Networking defaults to `VZNATNetworkDeviceAttachment` for isolated connectivity, with optional bridged mode via `VZBridgedNetworkDeviceAttachment` for direct LAN access.

## VM Lifecycle and Asynchronous Control

Lume wraps the framework's imperative APIs in Swift's `async`/`await` patterns within `BaseVirtualizationService`. The `start()` method creates a `VZVirtualMachine` instance from the configuration and initiates execution on the physical CPU cores.

```swift
func start() async throws {
    try await withCheckedThrowingContinuation { continuation in
        Task { @MainActor in
            if #available(macOS 13, *) {
                let opts = VZMacOSVirtualMachineStartOptions()
                opts.startUpFromMacOSRecovery = recoveryMode
                virtualMachine.start(options: opts) { error in
                    error.map { continuation.resume(throwing: $0) } ?? continuation.resume()
                }
            } else {
                virtualMachine.start { result in
                    switch result {
                    case .success: continuation.resume()
                    case .failure(let err): continuation.resume(throwing: err)
                    }
                }
            }
        }
    }
}

```

The `stop()`, `pause()`, and `resume()` methods similarly bridge to `VZVirtualMachine` equivalents, providing non-blocking control for the HTTP API.

## macOS Installation and Image Management

Lume automates macOS provisioning through [`DarwinVM.swift`](https://github.com/trycua/cua/blob/main/DarwinVM.swift), which orchestrates the download of IPSW images and extraction of hardware model data.

The `setup` method initiates the process, calling `DarwinVirtualizationService.installMacOS` to invoke `VZMacOSInstaller`. This streams the restore image directly into the virtual hardware while reporting progress via KVO observation on the installer's `fractionCompleted` property.

```swift
let installer = VZMacOSInstaller(
    virtualMachine: virtualMachine,
    restoringFromImageAt: imagePath.url
)
installer.install { result in
    switch result {
    case .success: continuation.resume()
    case .failure(let err): continuation.resume(throwing: err)
    }
}

```

## Why Lume Achieves Near-Native Performance

Lume delivers bare-metal execution speeds through several framework optimizations:

- **Direct Hypervisor Access** - The guest runs directly on Apple Silicon cores without binary translation or emulation layers, as implemented in the `VZVirtualMachine` initialization within [`VMVirtualizationService.swift`](https://github.com/trycua/cua/blob/main/VMVirtualizationService.swift).

- **Paravirtualized Device Drivers** - Virtio block, network, and graphics devices eliminate emulation overhead by allowing the guest to perform I/O through shared memory rings rather than simulating physical hardware.

- **GPU Composition** - `VZMacGraphicsDisplayConfiguration` enables direct framebuffer mapping to the host's window server, reducing latency for screen capture operations essential to the CUA SDK.

- **Efficient Resource Management** - Memory ballooning devices and paravirtualized entropy sources minimize guest stalls and reduce host resource contention.

## Key Source Files

The implementation spans these critical paths in the `trycua/cua` repository:

- **[`libs/lume/src/Virtualization/VMVirtualizationService.swift`](https://github.com/trycua/cua/blob/main/libs/lume/src/Virtualization/VMVirtualizationService.swift)** - Defines `BaseVirtualizationService` and `DarwinVirtualizationService`, handling `VZVirtualMachineConfiguration` assembly and lifecycle management.

- **[`libs/lume/src/VM/DarwinVM.swift`](https://github.com/trycua/cua/blob/main/libs/lume/src/VM/DarwinVM.swift)** - Implements macOS-specific VM logic, including IPSW downloading, hardware model parsing, and installation orchestration through `setup()` and related methods.

- **[`libs/lume/src/LumeController.swift`](https://github.com/trycua/cua/blob/main/libs/lume/src/LumeController.swift)** - Entry point for CLI commands and HTTP server routing, translating API requests into runtime actions.

- **`docs/content/docs/lume/guide/getting-started/introduction.mdx`** - High-level documentation explaining the Virtualization Framework integration.

## Summary

- Lume provides a Swift runtime over Apple's Virtualization Framework, exposing CLI and HTTP interfaces for VM management.

- **Hardware acceleration** is achieved through direct `VZVirtualMachine` instantiation with native CPU execution and paravirtualized Virtio devices.

- **Graphics performance** relies on `VZMacGraphicsDeviceConfiguration` mapping VM framebuffers to host compositors for low-latency rendering.

- **macOS provisioning** automates IPSW download and `VZMacOSInstaller` execution via [`DarwinVM.swift`](https://github.com/trycua/cua/blob/main/DarwinVM.swift) and `DarwinVirtualizationService`.

- **Asynchronous lifecycle control** wraps framework callbacks in Swift concurrency patterns for non-blocking API operations.

## Frequently Asked Questions

### What makes Lume faster than traditional macOS virtualization?

Lume achieves near-native performance by utilizing Apple's Virtualization Framework to run guests directly on Apple Silicon hypervisors without emulation. Unlike traditional x86 virtualization that requires binary translation, Lume configures `VZVirtualMachine` instances that execute native ARM64 instructions on physical cores, while paravirtualized storage and network devices minimize I/O overhead.

### How does Lume handle graphics and display output?

Lume configures graphics through `VZMacGraphicsDeviceConfiguration` in [`VMVirtualizationService.swift`](https://github.com/trycua/cua/blob/main/VMVirtualizationService.swift). When a host display is present, it creates a `VZMacGraphicsDisplayConfiguration` that maps the VM's framebuffer directly to the host's window server, enabling hardware-accelerated composition and fast screenshot capture required for the CUA Computer SDK's visual observations.

### Can Lume run Linux VMs as well as macOS?

Yes. While the primary focus is macOS through [`DarwinVM.swift`](https://github.com/trycua/cua/blob/main/DarwinVM.swift), the architecture includes [`LinuxVM.swift`](https://github.com/trycua/cua/blob/main/LinuxVM.swift) as a concrete subclass of the abstract `VM` type. Both implementations share the same `BaseVirtualizationService` infrastructure but configure different platform settings appropriate to their respective operating systems.

### Where does Lume store VM configuration and auxiliary data?

Lume stores the hardware model, machine identifier, and NVRAM data in auxiliary storage files managed through `VZMacAuxiliaryStorage`. The `DarwinVirtualizationService.createConfiguration` method binds these to the `VZMacPlatformConfiguration`, ensuring each VM maintains persistent identity and boot state across restarts.