MacVisor

Security model

Which component runs with which privileges, which VM features cross the guest boundary, which macOS permissions MacVisor asks for, and what leaves your Mac.

Everything that manages VMs runs as the logged-in user: the app, the mvz CLI, the background service and every VM runner. One small helper runs as root, for the few jobs that need it.

The app, CLI, service and runners run as you. One root helper owns the firewall, VLAN interfaces, CLI links, resolver files and the Mac's license. The guest agent sits on the far side of the VM boundary.

Privileges

ComponentRuns asRole
MacVisor app, mvz CLIYouClients of the background service. They don't own VM processes
MacVisorServiceYou, as a login agentOwns the VM library and starts runners
MacVisorVMRunner (MacVisor VM.app)You, one per running VMRuns the virtual machine and its devices
MacVisorNetworkHostYouRuns custom shared and host-only networks
MacVisorTPMEngineYou, one per running VM with a TPM, in the App SandboxRuns the VM's TPM (libtpms). It reads what the guest sends, so it has no network, files or devices: only the pipes to its VM's runner
MacVisorAdminHelperroot, approved onceThe only changes MacVisor makes to the Mac as root, and the Mac's license

The root helper

Setup calls it the Network Helper. It is a launch daemon, approved once with an administrator password, and it does five things:

  1. Loads firewall rules into pf.
  2. Creates and deletes 802.1Q VLAN interfaces.
  3. Links /usr/local/bin/mvz and /usr/local/bin/macvisor.
  4. Writes /etc/resolver/mvz and /etc/resolver/macvisor, so <vm>.mvz and <vm>.macvisor lookups reach MacVisor.
  5. Holds the MacVisor license for every account on the Mac, in /Library/Application Support/MacVisor/Licensing, which only root can read, and beside it vm-roster.json, the ids of the VMs the Mac had while it was licensed or in its trial (see VMs added after the trial or license ended). A file beside it, licensing-device-key, is readable by any account and holds only a hash of the public half of the device key. See Licenses on a Mac with several accounts.

It also reads the Mac's ARP table for a VM's own MAC addresses, so MacVisor can show the address of a VM without the agent. While any network's firewall is on, it stays running; otherwise it exits when idle, and launchd starts it on the next request.

It installs only from a copy of MacVisor that only an administrator can change, such as the one in /Applications, so a standard account can't swap the code it runs.

It answers only the MacVisor app and background service, verified by code signature, and it checks who is asking:

RequestWho may make it
Create or delete a VLAN interfaceAn administrator. The helper deletes only VLAN interfaces it created
Firewall policy, the mvz and macvisor links, the resolver filesAn administrator, or the user at the Mac's screen
Start the Mac's one trial, or activate a keyAny account, standard or administrator
Deactivate the Mac's license (which releases it for every account), or Remove Trial from This Mac…An administrator, or the account that activated it

The CLI links point only into a copy of MacVisor that only an administrator can change. They go only into a /usr/local/bin that is a real folder under administrator control, and the helper never replaces a file there that isn't a MacVisor link.

The helper accepts a firewall policy, never packet-filter text, and compiles the rules itself. It checks every subnet again: rules apply only to a subnet inside 192.168.0.0/16, sized /20 to /30, and a subnet that overlaps one of the Mac's own networks gets its rules on the network's own bridge only, never on the Mac's other interfaces. A compromised user-level process can only ask for what the firewall editor can already express, not for root control of the Mac's networking.

Uninstalling MacVisor from an administrator account clears the helper's firewall rules and unregisters it. From a standard account, only that account's rules are cleared and the helper stays. Your networks keep their rules: after a reinstall MacVisor applies them again.

The guest boundary

A VM is isolated by design. Each feature that crosses that boundary is opt-in and visible:

  • Shared folders expose the Mac folders you choose. Share only what the guest needs, read-only where you can.

  • Clipboard sharing works both ways by default. Per VM, you can limit it to Mac-to-VM (the guest can't change your clipboard), VM-to-Mac (the guest never sees it), or turn it off. The Mac's clipboard is sent only while the VM's window is active, and never what a password manager copies. What the guest copies reaches the Mac only when you leave the VM's window, and a headless or hidden VM never sets the Mac's clipboard. A Linux VM that uses spice-vdagent, such as an Ubuntu Desktop VM, is the exception: at Both Ways it gets everything you copy, passwords included, at any time. See Guest tools.

  • Files sent from the guest to the Mac always need your approval on the Mac.

  • The guest agent proves itself. Before MacVisor sends the agent anything private (the clipboard, files, shell and tunnel connections, port-forwarded connections, its access token), the agent answers a challenge with the VM's own key, which only root in the guest can read (on a macOS guest, the agent's own account). Another account in the guest that takes the agent's ports gets nothing, and MacVisor flags the agent as Not Trusted. See Agent authentication.

  • A VM's port forwards listen on this Mac only (127.0.0.1 and ::1), and go through the guest agent rather than the network, so the network firewall doesn't filter them. Other devices reach a VM only through a bridged network or a custom network's port forwarding. See Port forwarding.

  • Automatic port forwarding is on by default for Linux VMs made from cloud images and has no approval step: the list of ports it holds back is its trust model. Forwarded ports appear only on the Mac's loopback (127.0.0.1 and ::1), never on its other interfaces, and ports where the Mac's own services usually listen are held back. A process in the guest can still take any other free loopback port, so a Mac tool that connects before its own service starts reaches the guest. Turn it off per VM under VM Settings → Cloud-Init → Forward guest ports automatically, or create the VM with --no-forward. See What automatic forwarding leaves out.

  • USB passthrough gives the guest a real device. The guest's driver then talks to your hardware directly.

  • Rosetta and nested virtualization are set per VM and shown in its settings.

  • Imported bundles are treated as data, not as trusted settings. Importing a bundle (.mvz, .mvzt, or .macvisor from an earlier build) from elsewhere removes its shared folders and external disk images, clears USB auto-capture, turns off start at login and high availability, pins port forwards and remote access to 127.0.0.1, closes it to AI agents, and fixes invalid guest account names. MacVisor lists what it changed. A bundle whose configuration names disk files outside the bundle, or that contains links (a disk that points at a file elsewhere, say), is refused. A bundle that turns up in a storage location without being imported is treated the same way, once on each Mac, and loses its AI sandbox settings too. See Storage and sharing.

  • AI agents reach a VM through MacVisor's MCP server only if you open it to them, per VM, at View or Control. Every VM starts closed, copies and imports start closed, and a revert keeps the current setting. Agents can't delete snapshots, change settings, read the account passwords MacVisor keeps, or delete VMs they didn't make, and every tool call is logged. See AI agents and MCP.

The agent in a macOS guest

The agent is an ordinary login item named MacVisor Agent, which you can switch off in the guest's own Login Items & Extensions. It runs as the signed-in guest user, without elevated rights.

Automatic setup also adds /etc/sudoers.d/macvisor-shutdown. It lets that account run shutdown -h now, and nothing else, without a password, so MacVisor can stop the VM cleanly when the agent isn't connected. Delete the file in the guest to undo it.

Setup that crosses the boundary once

  • Linux cloud-image VMs are configured by cloud-init with your user name and UID, and the public SSH keys from ~/.ssh and your SSH agents (or only the ones you pass with --ssh-key). Your home folder is shared read-only at the same path only if you ask, with --home or Share my home folder (read-only) in the New VM form. Nothing private leaves the Mac, but a read-only home folder is still your home folder. Leave it off for guests you don't trust, and check the box before you create one, because the form remembers your last choice.
  • macOS 27 guests with automatic setup and Remote Login are signed into once by MacVisor, over SSH with the account's password, to authorise your SSH keys and install the agent. MacVisor then turns SSH password logins off, so the guest accepts keys only. Later agent updates use MacVisor's own key, ~/.macvisor/ssh/id_ed25519. The default account name (macvisor) is public knowledge and still works at the guest's login window. Change it on any VM that others can reach.
  • Windows VMs with Remote Login get OpenSSH Server during setup, with your SSH keys authorised, and accept keys only: the account's password is for the login window and Remote Desktop.

Network isolation

Host-only networks keep guests off external networks entirely. A custom network's firewall adds inbound and outbound rules enforced on the Mac, where the guest can't turn them off. Its limits are listed in Network firewall. Bridged mode is the opposite: the VM is a device on your LAN, subject only to what your network enforces.

macOS permissions MacVisor asks for

  • Background item approval for the background service, and one administrator password for the network helper, during first-run setup.
  • Files & Folders access when VMs are stored on a removable, network or otherwise protected volume. The background service asks once when it scans the library, and the VM runner asks once when it first starts a VM stored there.
  • Local Network access for the app and the VM runner. VMs sit on a local network of their own, and since macOS 15 no app can reach one without consent. MacVisor needs it for its own connections to a guest's address, such as the account and agent setup in a macOS 27 guest. mvz shell, exec, Docker contexts and port forwards go through the guest agent instead. Commands you run in a terminal against a guest's address (curl http://dev.mvz:8080) use the terminal app's permission. To check the permission and prompt macOS to ask, the app and runner send a one-byte packet to the local multicast DNS group (224.0.0.251:5353), which never leaves the local network. See Install and activate, or open Assistant → Setup Assistant….
  • Microphone access, the first time a VM set to receive the Mac's microphone input records from it. Every new Windows VM is, through MacVisor's audio device, until you turn its microphone off.

What leaves your Mac

  • VM data never does. Bundles, disks and snapshots stay on the Mac, and guest traffic never passes through ScaleNinja's servers.

  • License checks go to ScaleNinja's licensing server, keys.scaleninja.com on port 443. See Activate your license. They happen:

    • when MacVisor starts the free trial, on a Mac with neither a license nor a trial once its License Agreement is accepted (right after you accept it, and otherwise whenever MacVisor opens, such as after a deactivation), with retries while it gets no answer (after 30 seconds, 2 and 10 minutes, then every 30 minutes, and when you bring MacVisor to the front, at most once a minute for the first hour, then once every 10 minutes) until it starts or the server refuses it; when you run mvz license trial; and when you activate, refresh, deactivate or move a license;
    • every few days, when the last answer is three days old, during a trial too;
    • after MacVisor updates;
    • after a license or trial ends, to look for a renewal;
    • to confirm a licensing record this Mac couldn't verify, or to finish a deactivation made offline;
    • after a check that got no answer: again after 5 minutes, then every 15 minutes;
    • when you try a licensed action while MacVisor waits for the server's answer, at most every 30 seconds.

    A check carries a SHA-256 hash of the Mac's hardware UUID and one of its serial number (never the raw values), its model (never its computer name), the MacVisor and macOS versions, and a random one-time value. With the Network Helper on, it also carries the public half of a device key, which proves later checks come from the same Mac. Activating, refreshing and deactivating also send the license key. Your email is never sent, and nothing about your VMs is. The server's answers are signed and checked on the Mac. Polar receives nothing from MacVisor; to check a key, the licensing server sends Polar only the key. What the server keeps, and for how long, is in the privacy policy.

  • Update checks download a signed release feed from scaleninja.com once a day, when enabled. Updates are verified against MacVisor's signing key. With Download and install updates automatically on, the default, MacVisor downloads and installs them by itself, also while the app is closed; turn it off in Settings → Updates to be asked first. Running VMs are not interrupted.

  • Image and installer downloads go to the sources listed in the catalogue (the distributions' download servers and Apple's CDN), only when you ask for an image. Some distribution servers redirect to third-party mirrors. Every file is checked before use against a checksum pinned in the signed catalogue or read over HTTPS from the distribution's checksum list. Only a file with such a checksum may arrive over plain HTTP, which a mirror sometimes redirects to. One exception: when Apple offers a newer build than the catalogue lists, macos-latest downloads it over HTTPS from the address Apple gives, with no checksum to check. Name a catalogue installer such as macos-27 to have it checked.

  • Software a VM needs is downloaded on the Mac, only for a VM that needs it, and checked against a SHA-256 pinned in MacVisor. For Windows VMs: the virtio-win drivers from fedorapeople.org, and from GitHub WinFsp, usbip-win2 and, with Remote Login, OpenSSH for Windows, written onto the VM's installation media. For Linux VMs with the containerd or k3s runtime: nerdctl, or k3s and its installer, from GitHub (github.com, raw.githubusercontent.com), kept on the Mac and shared read-only with the VM.

  • Inside the guest, cloud-init installs the runtime you chose from the distribution's repositories, download.docker.com (Docker on the RHEL family), GitHub (nerdctl, or k3s and its installer, when the Mac's copy isn't there yet) and, for k3s on some SELinux distributions, Rancher's package repository. k3s then pulls its container images from public registries. That is the guest's own traffic.

  • AI sandbox model requests (Tech Preview) go to a cloud provider (Anthropic, OpenAI or OpenRouter) only when a sandbox uses that provider's model and you have stored its key. MacVisor adds the key from the Keychain as the request leaves the Mac. A sandbox set up with a local model uses cloud models only if you allow them. With allowlist and none internet access, MacVisor doesn't let the provider fetch pages, search the web live or reach MCP servers for the agent, unless you allow that for the sandbox. It refuses such requests, but sends one that asks for a live web search on with the cached search, or on an OpenRouter model without it. Requests to a local model server stay on the Mac. Models you download with mvz models pull are fetched from Hugging Face, checked only against the size Hugging Face lists for a single-file model, or by your local model server from its own registry. mvz models server install uses Homebrew. See AI sandboxes.

  • Problem reports are created only when you ask and saved to a file you choose. Nothing is sent unless you send it, by attaching it to an email yourself or with Email to Support, which opens your mail app with the report attached. They contain MacVisor's logs, including the network helper's log with its activity for every account on the Mac, its task history, MacVisor crash reports from the last 14 days (from ~/Library/Logs/DiagnosticReports and /Library/Logs/DiagnosticReports), the crash, hang and resource reports of the Virtualization process that ran your VMs, the end of each VM's serial console log, which can show what the guest printed, and a summary of your VMs (names, ids, settings, package paths) and networks.

Apart from license checks and update checks, MacVisor makes no routine network traffic of its own. The image catalogue ships inside the app and is never fetched.

Protecting VM data at rest

A VM's bundle (.mvz, or .macvisor from an earlier build) holds the guest's whole disk. It doesn't hold the password of the VM's account: see Where VM passwords live.

MacVisor doesn't encrypt VM bundles itself. FileVault is the right protection for this, at the cost of unattended reboots. A VM's TPM is the exception: its state is sealed to this Mac's Secure Enclave, so a copy of the bundle on another Mac can't open it, and a Windows disk that BitLocker sealed to it needs its recovery key there, unless you move the TPM with it. See Always-on host. Keep VMs on an external drive only if it is an encrypted APFS volume.

Where VM passwords live

A macOS VM with automatic setup, every Windows VM, a Linux VM with Ubuntu Desktop and a FreeBSD VM have a password for their first account, the one MacVisor made (shown on the macOS VM card of a macOS VM's Overview): random for each VM unless you chose one. MacVisor stores it in your login Keychain as a MacVisor item, not in the VM's files or its configuration. MacVisor's background service reads it there without asking; any other app needs your permission. An Ubuntu Desktop or FreeBSD guest gets only a hash of it.

MacVisor shows, copies, types or prints it only after you confirm with Touch ID or your Mac's password at the Mac: Show Password, Copy Password and Type Password in the app, and mvz password <vm> in Terminal. A confirmation in the app lasts five minutes for that VM in that app only, and ends when the screen locks or the Mac sleeps. mvz password asks every time, and refuses over SSH or anywhere macOS can't show the prompt. AI agents, scripts and SSH sessions never get it. Type Password sends it only as keystrokes into the VM's window, never through the clipboard. The New VM form doesn't remember it. For automation, bring a password of your own; see Automation and passwords.

Because it isn't part of the VM's files, exports and backups don't contain it, and a VM imported or restored on another Mac has no saved password. On the other Mac, give it to MacVisor again with mvz password <vm> --set: MacVisor keeps it as one given at create, and the account in the VM doesn't change. It asks nothing while MacVisor has none for the VM; replacing one it has needs Touch ID or your Mac's password at the Mac. See Moving a VM to another Mac. Moving a VM to the Trash keeps its password, so Put Back brings it back, and the password stays in the Keychain once the Trash is emptied, or the VM is deleted in Finder. mvz password --prune lists the passwords of VMs MacVisor can't find any more and deletes them once you confirm (--dry-run only lists them); it never offers the password of a VM MacVisor moved to the Trash. See Account password. A VM made with an earlier version keeps its password in the bundle's .host-secrets folder until it next stops, when MacVisor moves it into the Keychain and deletes the file.

A password you chose when making the VM is deleted by itself once setup is done; the Task History says when. For Ubuntu Desktop the guest agent must report that setup is over: with guest tools off, the password stays until you delete it. A random one stays until you choose Delete Password… on the VM's Overview, or run mvz password <vm> --delete. Copy or show it first if you'll need it. That works once MacVisor no longer needs it: a macOS VM's automatic setup, a Windows VM's install or an Ubuntu Desktop or FreeBSD VM's setup has finished. It also waits while a snapshot taken before setup finished exists, because reverting to it or copying it sets the account up again: delete that snapshot first. The automatic deletion waits for it too. Then MacVisor has no copy: Copy, Show and Type Password and mvz password stop working. The account keeps its password, and nothing changes inside the guest, including what the guest's own automatic login keeps there. It can't be undone.