macOS QEMU Guest Agent

A native QEMU Guest Agent for macOS and OS X virtual machines. The missing guest agent for Mac — enables Proxmox VE, libvirt, plain QEMU, and UTM to manage macOS guests through the standard QGA protocol.

45 commands, real filesystem freeze, zero dependencies. Supports Mac OS X 10.4 Tiger through macOS 26 Tahoe. Works as both a macOS guest agent and an OS X guest agent for legacy VMs.

Quick Start (Proxmox VE)

1. On the PVE host — enable the guest agent:

qm set <vmid> --agent enabled=1,type=isa
qm stop <vmid> && sleep 5 && qm start <vmid>

Why type=isa? macOS Big Sur and newer include Apple's own built-in VirtIO guest agent which claims the default VirtIO serial channel. Using type=isa ensures our agent gets its own dedicated serial channel via Apple16X50Serial.kext. This is required on all macOS versions.

2. In the macOS VM:

# Download binary (from a modern machine if VM can't reach GitHub)
curl -L -o mac-guest-agent https://github.com/mav2287/mac-guest-agent/releases/latest/download/mac-guest-agent-darwin-amd64

# Install
sudo cp mac-guest-agent /usr/local/bin/mac-guest-agent
sudo chmod +x /usr/local/bin/mac-guest-agent
sudo /usr/local/bin/mac-guest-agent --install

3. Verify:

# From PVE host
qm agent <vmid> ping
qm agent <vmid> get-osinfo

# From inside VM
sudo mac-guest-agent --self-test

How It Works

The agent communicates via an ISA serial port (16550 UART) using Apple's built-in Apple16X50Serial.kext driver, present on every macOS since 10.4. No custom kexts, no SIP changes, no code signing.

Note: macOS Big Sur and newer ship with Apple's own built-in VirtIO guest agent (18 commands, no freeze support). The default VirtIO serial channel is claimed by Apple's agent, which is why type=isa is required — it gives our agent a dedicated channel with all 45 commands and full freeze support.

Compatibility

Binary	Arch	Min macOS
mac-guest-agent-i386	i386	10.4 Tiger
mac-guest-agent-darwin-amd64	x86_64	10.6 Snow Leopard
mac-guest-agent-darwin-arm64	arm64	11.0 Big Sur
mac-guest-agent-darwin-universal	x86_64 + arm64	10.6 / 11.0

ISA serial driver (Apple16X50Serial.kext) verified present with identical PCI class match on every macOS from 10.4 Tiger (2005) through 26.3 Tahoe (2026). See the compatibility matrix for per-version evidence.

Service Management

sudo launchctl list com.macos.guest-agent     # Status
sudo launchctl start com.macos.guest-agent    # Start
sudo launchctl stop com.macos.guest-agent     # Stop
tail -f /var/log/mac-guest-agent.log          # Logs
sudo mac-guest-agent --uninstall              # Remove

Building from Source

make build              # Current architecture
make build-x86_64      # Intel (10.6+)
make build-arm64       # Apple Silicon (11.0+)
make build-universal   # Fat binary
make test              # Run all tests

Documentation

Guide	Description
Proxmox VE	VM settings, backup config, TRIM, security profiles, troubleshooting
libvirt / virt-manager	Domain XML, virsh commands, quiesced snapshots, troubleshooting
UTM	Local macOS VM automation, utmctl integration, CI/CD workflows
All Platforms	Plain QEMU setup, transport priority
Commands	All 45 commands with status, Linux parity, privilege requirements
Compatibility	Support tiers, kext timeline, verification evidence per version
Backup & Freeze	Filesystem freeze, APFS snapshots, hook scripts, TRIM
Security	Trust model, recommended profiles, freeze-state restrictions
Architecture	Data flow, protocol spec, macOS API usage
CLI Reference	All flags, config file format, examples
Changelog	Release history
Contributing	Build, style, testing guidelines

License

MIT