MacVisor

Architecture and operating modes

How MacVisor's background service and per-VM runners let the same VMs serve desktop use, an always-on host, and headless automation.

MacVisor keeps the app, the management service and each running VM in separate processes. That lets the same installation work as a desktop app, an always-on virtualization host, or a scripted CI machine.

MacVisor's clients, control service, one runner process per VM with its guest agent, the network host, and the root admin helper.

Three ways to use it

ModeWhat it looks like
DesktopVMs in native windows with display, sound, clipboard, shared folders and USB devices. Closing a window leaves the VM running.
Always-on hostVMs run headless, start at login, and keep running with no window open. Named networks, port forwards and guest tools support long-running services and multi-VM labs. See Always-on host.
Headless automationmvz creates VMs, opens shells, and drives snapshots, files and ports from scripts, for CI, tests and isolated agent workloads. See Using the CLI.

Components

ComponentRole
MacVisor app and mvzClients. They show state and request changes. Neither owns a VM process.
MacVisorServiceThe background service, a login agent. It manages the library and tasks, downloads and verifies images, starts runners, handles autostart, answers <vm>.mvz lookups, and checks the license.
MacVisorVMRunnerOne process per running VM, in the app MacVisor VM (MacVisor VM.app), shown by the VM's name in Force Quit and Activity Monitor. It owns the VM's display and devices. If it fails, only that VM is affected.
MacVisorNetworkHostHosts the named shared and host-only networks. NAT and bridging use Apple's networking directly.
MacVisorAdminHelperShown as Network Helper during setup, and the only component that runs as root. It applies firewall rules, creates VLAN interfaces, installs the mvz links and the .mvz resolvers, reads the Mac's ARP table for the addresses of VMs without the agent, and holds the license for every account on the Mac. It stays running while any network's firewall is on. See Security model.
MacVisor AgentOptional, inside the guest. It talks to its runner over a virtual socket, not the guest's network, and provides guest information, clipboard, file transfer, port tunnels and the connection behind mvz shell.

Host and guest data paths for display, storage, networking, and guest tools.

What survives what

EventEffect
The app or mvz quits or restartsNothing. Clients reconnect and VMs keep running.
A VM runner failsOnly that VM stops.
The service restarts or updatesRunners keep running, including a macOS install in progress. Management is unavailable for a moment while the service reconnects to the running VMs and resumes its tasks.

A restart you start from the dashboard or mvz service restart lets work in progress, such as a clone or an export, finish first: mvz service restart names that work and asks (--yes in a script), and --cancel calls a waiting restart off. High availability keeps restarting VMs meanwhile, and a restart it still owes survives the service's restart. After a MacVisor update, the app restarts a service that is still on the old build. mvz tells you to run mvz service restart if it finds one.

A macOS restart, a power cut, or a failure in shared host infrastructure still affects every VM. Snapshots and host backups cover those cases.

MacVisor isolates GUI, control-plane, and VM-runner failures, then reconciles surviving runners after service recovery.

Storage on other volumes

macOS asks before a background process reads a removable, network or protected folder. The service checks each storage location separately, so one location waiting for your permission doesn't hold up the rest of the library. A waiting location shows in the sidebar and in mvz service status.

Acknowledgements

MacVisor uses Sparkle 2.10 for software updates, under the MIT licence. That licence also covers the bsdiff, sais-lite, ed25519 and SUSignatureVerifier code included in Sparkle.

The Linux guest agent is written in Go and includes the Go standard library and runtime, under the Go licence (BSD-style).

The guest operating system icons are their owners' logos and trademarks, used only to identify the system a VM runs. The macOS icon comes from Font Awesome Free (CC BY 4.0). Tux was originally drawn by Larry Ewing with The GIMP.