macOS host
vee runs on Apple Silicon Macs using Hypervisor.framework (HVF) with aarch64 guests and accelerated virtio-gpu.
For macOS guests, vee uses Apple’s Virtualization.framework instead of QEMU — see macOS guests.
- Apple Silicon (arm64). Intel Macs may work under TCG but are untested.
- A
qemu-system-aarch64onPATH(Homebrew QEMU works for basic use).
HVF only accelerates guests whose architecture matches the host, so guests must be aarch64. x86 guests fall back to slow TCG software emulation.
vee uses the virt machine type, edk2 ARM (AAVMF) firmware, and a windowed cocoa display.
| Feature | Status on macOS |
|---|---|
| Boot / lifecycle / cloud-init | Works (built-in ISO writer, or hdiutil fallback — no xorriso needed) |
| Accelerated virtio-gpu (virgl) | Works with a virgl-capable QEMU; software (llvmpipe) otherwise |
| Networking | User-mode NAT only |
| VFIO GPU passthrough | Unavailable (Linux-only) — warns and degrades |
| virtiofs shares | Unavailable |
| vsock SSH-agent sharing | Unavailable |
| swtpm TPM | Unavailable |
| Bridge networking | Unavailable |
vee warns and falls back rather than emitting broken QEMU arguments.
Ubuntu and Fedora cloud images ship arm64 builds and work out of the box, and the windows template builds Windows 11 / Windows 10 arm64 install media on demand (2D ramfb display — use RDP for a desktop). The ubuntu-server live ISO, Arch/gaming-arch, Bazzite, Alpine/docker, and TrueNAS templates are x86-only and not wired for arm64.
Linux guests can run their own VMs (Docker Desktop for Linux, KubeVirt, qemu -accel kvm) with vee create <name> --nested, or nested: true in the VM’s vm.yaml. Under HVF this needs an M3-or-later Mac on macOS 15+, and the guest kernel needs ARM nested-virt support (Fedora 41+); vee’s pinned QEMU bundle (11.1.0-rc2) carries the required HVF EL2 support. macOS guests can never nest — Apple’s frameworks do not work inside a VM.
The virgl-accelerated vee-qemu bundle for macOS is not currently buildable: QEMU 10.0.2 and the only macOS-patched virglrenderer (a 2021-era fork around QEMU 6.2) do not compile together. Venus/Vulkan is experimental. QEMU’s own macOS-guest path (apple-gfx + vmapple) is unusable upstream — macOS guests run on the vz backend instead.
The QEMU binary vee uses is code-signed with the com.apple.security.hypervisor entitlement (vee applies an ad-hoc signature automatically).
See docs/macos.md for the full per-guest GPU matrix and setup details.