Cross-platform VM lifecycle management. macOS via Apple Virtualization.framework, Linux via Cloud Hypervisor.
Status: experimental and under active development. This matrix reflects current implementation work, not a maturity or production-readiness guarantee.
| Capability | macOS (Apple VZ) | Linux (Cloud Hypervisor) | Notes |
|---|---|---|---|
| Lifecycle | |||
| Boot VM | Supported | Supported | Kernel + initramfs + root disk |
| Stop (graceful) | Supported | Supported | ACPI shutdown |
| Kill (force) | Supported | Supported | Immediate termination |
| Query state | Supported | Supported | Starting → Running → Ready → Stopped / Failed |
| Reboot | Not supported | Planned | CH: vm.reboot or ch-remote reboot |
| Delete/cleanup | Supported | Supported | Remove VM state and resources |
| CPU | |||
| Set vCPU count | Supported | Supported | At boot time |
| CPU hotplug | Not possible | Planned | CH: vm.resize --cpus N (up to max_vcpus) |
| CPU topology | Not possible | Planned | Sockets / cores / threads |
| CPU affinity | Not possible | Planned | Pin vCPUs to host cores |
| Memory | |||
| Set memory size | Supported | Supported | At boot time |
| Memory balloon | Supported (FFI wrapped) | Planned | Dynamic guest memory reclaim |
| Memory hotplug | Not possible | Planned | CH: vm.resize --memory N |
| Hugepages | Not possible | Planned | 2MB / 1GB pages |
| Memory zones (NUMA) | Not possible | Planned | Per-zone backing and pinning |
| Storage | |||
| Root disk | Supported | Supported | VirtioBlock |
| Seed ISO (cloud-init) | Supported | Supported | Second disk, read-only |
| Data disk | Supported | Supported | Additional VirtioBlock |
| Disk hotplug | Not possible | Planned | CH: vm.add-disk |
| Disk resize | Not possible | Planned | CH: vm.resize-disk |
| Disk CoW clone | Supported (APFS) | Supported (reflink) | Instant base image cloning |
| Disk caching modes | Supported | Planned | Uncached / Cached / Auto |
| Disk rate limiting | Not possible | Planned | Token bucket throttle |
| Networking | |||
| NAT (internet access) | Supported | N/A | macOS: built-in NAT attachment |
| TAP devices | N/A | Supported | Linux: standard TAP networking |
| Socketpair (L2 switch) | Supported | N/A | macOS: userspace Ethernet switch |
| Custom MAC address | Supported | Supported | Per-VM unique MAC |
| Network hotplug | Not possible | Planned | CH: vm.add-net |
| Bridged networking | Supported (FFI wrapped) | Planned | Direct host NIC bridge |
| vhost-user net | Not possible | Planned | Offload to external daemon |
| Shared Directories | |||
| VirtioFS | Supported (in-process) | Planned | macOS: native VZ. Linux: virtiofsd sidecar |
| Read-only mounts | Supported | Planned | Immutable shared data |
| Serial Console | |||
| File output | Supported | Supported | Log serial to file |
| Readiness detection | Supported | Supported | Parse VMRS_READY <ip> marker from console |
| Entropy | |||
| VirtIO RNG | Supported | Supported | /dev/random in guest |
| Advanced (API mode) | |||
| Pause / Resume | Not possible | Planned | CH: vm.pause / vm.resume |
| Snapshot | Not possible | Planned | CH: vm.snapshot — full state dump |
| Restore | Not possible | Planned | CH: vm.restore — resume from snapshot |
| Live migration | Not possible | Planned | CH: vm.send-migration / vm.receive-migration |
| VM counters/metrics | Not possible | Planned | CH: vm.counters |
| Device Passthrough | |||
| VFIO (GPU, NIC, etc.) | Not possible | Planned | CH: vm.add-device |
| vDPA | Not possible | Planned | Hardware-accelerated virtio |
| Inter-VM Communication | |||
| vsock | Not possible | Planned | CH: CID-based VM-to-VM / VM-to-host |
| L2 switch (userspace) | Supported | N/A | macOS: learning bridge via socketpairs |
| Platform-Specific | |||
| Rosetta (x86 on ARM) | Not wrapped | N/A | Apple Silicon: run x86_64 Linux binaries |
| macOS guest boot | Not wrapped | N/A | VZMacOSBootLoader |
| UEFI boot | Not wrapped | Planned | EFI variable store + firmware |
| TPM | Not wrapped | Planned | Virtual Trusted Platform Module |
| Watchdog | N/A | Planned | Guest hang recovery |
| Graphics/Display | Not wrapped | Not planned | Headless VMs only |
| Audio | Not wrapped | Not planned | Not needed for server VMs |
Supported = works now, tested. Planned = the underlying platform supports it; we haven't wired it yet. Not possible = the platform does not offer this capability. Not wrapped = Apple VZ framework supports it, but our FFI bindings don't expose it yet. Not planned = technically possible but not in scope (server-oriented crate).
In-process VM management. The VZ framework runs inside our process via Objective-C FFI.
VMs are created as VZVirtualMachine objects on a dispatch queue. We use Box::leak
to keep them alive (ObjC reference counting requires the object to outlive the queue).
Capabilities are fixed at boot — no hotplug, no resize, no snapshot. The framework is designed for desktop virtualization (macOS guests, Linux guests with GUI). We use only the headless Linux server subset.
Separate VMM process. We spawn cloud-hypervisor and manage the process lifecycle.
Two modes:
-
CLI mode (current) — boot with
cloud-hypervisor --kernel ... --cpus ... --disk .... Stop = SIGTERM (graceful ACPI), Kill = SIGKILL, State = process alive check. Simple, no dependencies, covers basic lifecycle. -
API mode (future) — boot with
cloud-hypervisor --api-socket /path/to/sock. Control viach-remoteCLI or direct HTTP over Unix socket. Required for: hotplug, resize, snapshot, restore, live migration, pause/resume.
We start with CLI mode and add API mode when advanced features are needed.
The VmDriver trait is designed to accommodate both.
For advanced features (API mode), Cloud Hypervisor exposes these endpoints
via HTTP over Unix socket. The ch-remote CLI wraps all of them.
| Endpoint | Method | Purpose |
|---|---|---|
vmm.ping |
GET | Health check |
vmm.shutdown |
PUT | Kill VMM process |
vm.create |
PUT | Create VM from JSON config |
vm.boot |
PUT | Start created VM |
vm.shutdown |
PUT | Graceful ACPI shutdown |
vm.reboot |
PUT | Guest OS restart |
vm.delete |
PUT | Remove VM |
vm.info |
GET | Query VM state and config |
vm.pause |
PUT | Suspend execution |
vm.resume |
PUT | Resume from pause |
vm.resize |
PUT | Change CPU count or memory size |
vm.resize-disk |
PUT | Expand disk |
vm.resize-zone |
PUT | Expand memory zone |
vm.add-disk |
PUT | Hotplug block device |
vm.add-net |
PUT | Hotplug NIC |
vm.add-fs |
PUT | Hotplug VirtioFS mount |
vm.add-device |
PUT | Hotplug VFIO device |
vm.add-vsock |
PUT | Hotplug vsock |
vm.add-pmem |
PUT | Hotplug persistent memory |
vm.add-vdpa |
PUT | Hotplug vDPA device |
vm.add-user-device |
PUT | Hotplug userspace device |
vm.remove-device |
PUT | Hot-unplug device |
vm.snapshot |
PUT | Snapshot full VM state |
vm.restore |
PUT | Resume from snapshot |
vm.send-migration |
PUT | Live migration (outbound) |
vm.receive-migration |
PUT | Live migration (inbound) |
vm.counters |
GET | Performance metrics |
vm.power-button |
PUT | Simulate power button |
vm.nmi |
PUT | Non-maskable interrupt |
vm.coredump |
PUT | Debug memory dump (x86_64) |
Our FFI bindings (absorbed from virtualization-rs, MIT license) wrap:
| VZ Class | Wrapped | Used by Driver |
|---|---|---|
| VZLinuxBootLoader | Yes | Yes |
| VZVirtualMachineConfiguration | Yes | Yes |
| VZVirtualMachine | Yes | Yes |
| VZVirtioBlockDeviceConfiguration | Yes | Yes |
| VZDiskImageStorageDeviceAttachment | Yes | Yes |
| VZVirtioNetworkDeviceConfiguration | Yes | Yes |
| VZNATNetworkDeviceAttachment | Yes | Yes |
| VZFileHandleNetworkDeviceAttachment | Yes | Yes |
| VZBridgedNetworkDeviceAttachment | Yes | No |
| VZVirtioConsoleDeviceSerialPortConfiguration | Yes | Yes |
| VZFileHandleSerialPortAttachment | Yes | Yes |
| VZVirtioEntropyDeviceConfiguration | Yes | Yes |
| VZVirtioTraditionalMemoryBalloonDeviceConfiguration | Yes | Yes |
| VZVirtioFileSystemDeviceConfiguration | Yes | Yes |
| VZSharedDirectory | Yes | Yes |
| VZMACAddress | Yes | Yes |
| VZEFIBootLoader | No | — |
| VZMacOSBootLoader | No | — |
| VZGraphicsDeviceConfiguration | No | — |
| VZAudioDeviceConfiguration | No | — |
| VZUSBDeviceConfiguration | No | — |
| VZTPMDeviceConfiguration | No | — |
| VZLinuxRosettaDirectoryShare | No | — |