Guest tools

The MacVisor Agent runs inside macOS, Linux, Windows and FreeBSD guests. VMs run without it, but these features need it:

• mvz shell, mvz exec and the Docker socket
• <vm>.mvz names and the guest's addresses in MacVisor
• The memory the guest uses, and its memory pressure, on the Overview's Memory card
• Clipboard sharing and file transfer
• Port forwarding
• A clean shutdown of macOS, Windows and FreeBSD guests
• Flushing the guest's writes to disk before a snapshot
• Correcting the guest clock after a pause, a resume or the Mac waking
• Keeping a macOS guest awake while MacVisor is connected to it
• A Linux VM's TPM: the agent puts MacVisor's TPM driver on the guest's EFI system partition and registers it with efibootmgr

The agent talks to MacVisor over a virtual socket, not the network, so it also works in a VM with no network. In a FreeBSD VM, which has no virtio-vsock driver, it uses a serial port instead.

On Windows, mvz shell and exec use OpenSSH instead of the agent, and there is no Docker socket. See Windows 11 guests.

In FreeBSD guests the agent gives the guest's details and addresses, file transfer, port forwards and a clean shutdown, but no clipboard sharing or shared folders. Without it, mvz shell and exec go over the network. See The MacVisor Agent on FreeBSD.

Installed for you

Install it by hand in any other VM: Linux from an ISO, a Linux appliance that lets you install software, a VM imported from another app, macOS 26 or earlier, or macOS 27 without automatic setup or Remote Login. Where it can't be installed, a QEMU guest agent gives a little of what it does.

In a macOS 27 guest, MacVisor also authorizes your SSH keys and makes two changes. It turns off SSH password logins with /etc/ssh/sshd_config.d/010-macvisor.conf, and adds /etc/sudoers.d/macvisor-shutdown so it can run shutdown -h now when the agent isn't connected. Delete either file in the guest to undo it.

Turn it on

In VM Settings → Guest Tools, turn on Enable Guest Tools and, for a manual install, Attach Guest Tools Image at Boot. The disc then mounts as MacVisor Agent at each start. A VM installed from an ISO has both on, and so do a new Linux appliance and a Linux VM imported from another app.

The guest tools disc

To attach the disc for one run only, click Attach Guest Tools at the top right of the Overview's Guest Tools card while the VM runs, choose VM → Attach Guest Tools in its window, or run mvz tools attach <vm>. Eject Guest Tools and mvz tools eject <vm> take it out again, and mvz tools status <vm> says whether it's in. None of these changes the VM's settings: what each start attaches stays in VM Settings → Guest Tools.

• Any Linux, macOS or FreeBSD VM can have the disc, appliances included. Windows setup installs its own agent, so a Windows VM has no button.
• A macOS VM's disc can be ejected while it runs, also one from the start, except in a VM resumed from a session saved by MacVisor 27.2.0, which keeps it until it shuts down. The USB Mass Storage card lists the disc as Guest Tools.
• A disc a Linux VM got at start can't be ejected while it runs. To leave it out, turn off Attach Guest Tools Image at Boot and restart the VM.
• The button is off when Allow Attaching USB Images While Running is off in VM Settings → Storage.
• A disc attached while the VM runs is ejected before a suspend or a live snapshot, because a saved session can't hold it. It goes back in after a live snapshot or a suspend that failed, and a paused VM gets it back when you resume it. A suspended VM resumes without it: attach it again. If the disc can't be ejected, the suspend or live snapshot isn't made and the VM is left as it was: shut it down instead. A suspend at logout goes ahead.
• A snapshot records the VM's settings, not the disc you attached or ejected, so reverting to it doesn't change them either.
• A stopped VM has nothing to attach the disc to, so its toolbar has no such button. What each start attaches is in VM Settings → Guest Tools.
• A VM that still runs on the MacVisor from before an update can get the disc attached once, and it stays in until the VM shuts down.

Install in a macOS guest

When the MacVisor Agent window opens in the guest:

1. Drag MacVisor Agent to Applications.
2. Open it from Applications, not from the disc.
3. If macOS asks, allow it in System Settings → General → Login Items & Extensions.

The agent runs from the menu bar and starts at every login. While MacVisor is connected to it, and for two minutes after a disconnect in case MacVisor comes back, it keeps the guest from going to sleep when idle (the guest's display can still sleep), so a VM without a window stays reachable over mvz shell and its port forwards. It doesn't keep the Mac itself awake. For mvz shell, turn on Remote Login in the guest's System Settings → General → Sharing. The first mvz shell asks for the password once and then uses your key.

Install in a Linux guest

With the guest tools disc attached, run:

sudo mount -o ro -L MACVISOR_AGENT /mnt && sudo sh /mnt/install-linux.sh

This installs the macvisor-agent service for systemd or OpenRC. The VM's Overview tab shows the same command: click it to copy it. In an appliance, it shows once the disc is in.

Install in a FreeBSD guest

MacVisor installs the agent over SSH by itself, or when you click Install Agent on the Overview. To do it by hand, attach the guest tools disc and run:

sudo mount -t cd9660 /dev/iso9660/MACVISOR_AGENT /mnt && sudo sh /mnt/install-freebsd.sh

This installs the macvisor_agent service. Enable Guest Tools must be on, and a VM made before must have been shut down once since you updated MacVisor. See The MacVisor Agent on FreeBSD.

Check and update

The VM's Overview tab shows whether the agent is connected, connecting, Updating (one from an earlier MacVisor, being replaced), Outdated (one MacVisor can't replace itself, with Update Agent) or Not Trusted (see Agent authentication). An appliance with no agent says Not Installed, with guest tools on or off. From the CLI, mvz wait <vm> waits until the agent answers.

MacVisor updates the agent itself in Linux, FreeBSD and Windows guests, and in macOS guests it set up. An outdated agent shows Update Agent on the Overview tab. For any other guest, install it again from the disc.

Which agent versions work

• Each MacVisor release works with its own agents and with the previous release's. A VM whose agent is one release behind keeps its shells, file transfers, clipboard, port forwards, guest information and shutdown until the agent is updated. An agent older than that isn't promised to work until MacVisor has updated it.
• MacVisor updates the agent by itself: in Linux, FreeBSD and Windows VMs as soon as the VM is running, with no restart, and in macOS VMs MacVisor set up automatically, over SSH. An agent you installed yourself in a macOS VM isn't updated for you: the Overview says it's older than MacVisor, and you drag MacVisor Agent from the MacVisor Agent volume into Applications again.
• A feature an older agent can't do yet is off, not broken. Each agent tells MacVisor what it can do, and MacVisor uses only that. Until the agent is updated, anything newer than it stays off, such as folders in file transfers or a Windows VM's visual effects.
• The exception is an agent from before MacVisor 27.2.1, which can't prove it is the VM's own (see below). Until MacVisor has updated it, the clipboard, file transfer, port forwards and the agent's shell and tunnel connections wait; guest information, shutdown and the update itself keep working. The Overview's Guest Tools card and mvz show say what is happening.

Agent authentication

From MacVisor 27.2.1, the agent proves it is the VM's own before MacVisor sends it anything private. Without this, any account in the guest could listen on the agent's ports while the agent wasn't running, at boot or during an update, and receive what MacVisor sends.

• A key per VM. MacVisor makes a random key for each VM and keeps it in the VM's package, in the .host-secrets folder only your account can read, never shared with the guest. In the guest, only the agent can read it:

  Guest	Where the key is
  Linux	/etc/macvisor/agent.key, readable by root only
  FreeBSD	/usr/local/etc/macvisor/agent.key, readable by root only
  Windows	C:\ProgramData\MacVisor\agent\agent.key, readable by SYSTEM and Administrators only
  macOS	~/Library/Application Support/MacVisorAgent/agent-key of the account the agent runs as

• A challenge on every connection. MacVisor sends a random value, and the agent answers with an HMAC-SHA256 of it under the key. Only then does MacVisor send the clipboard, files, shell, exec and tunnel connections, port-forwarded connections, or the agent's access token.

• How the key gets in. A new cloud-image Linux or FreeBSD VM gets it with its cloud-init setup, which only root can read, at every start; a new Windows VM with its installation media; a macOS VM MacVisor set up, over SSH. An agent installed before 27.2.1, or by hand, gets it from MacVisor the first time they meet after its update, on the connection the agent already holds. Uninstalling the agent leaves the key in place.

• An agent that can't prove itself where MacVisor expects it to is treated as a security event. MacVisor sends it nothing private, writes it to the VM's runner log, and the Overview and the VM's window say Not Trusted. Another account in the guest may be holding the agent's ports. If you reverted the VM to a snapshot taken before, or reinstalled the agent, click Update Agent on the Overview, which gives the agent the VM's key again.

An agent from 27.2.1 still works with MacVisor 27.2.0, which doesn't challenge it.

On the Mac, the VM's .secrets folder, which holds the agent's access token, is readable by your account only.

Clipboard

The clipboard is shared both ways by default. The Mac's clipboard is only sent while the VM's window is active. What you copy in the VM comes to the Mac when you leave its window, by switching to another window or app, as in VMware Fusion; while you work in the window, the Mac's clipboard stays as it is. A headless VM, or one whose window is hidden, never sets the Mac's clipboard. Text copied from apps that also copy its formatting, such as Safari, Mail or Xcode, reaches Linux and Windows VMs as plain text, and macOS VMs with the formatting. Passwords stay on the Mac: what a password manager copies, and MacVisor's own Copy Password, are marked as concealed and never sent. Use Type Password, or Show Password on the Overview, to get a VM's password in.

A Linux VM that uses spice-vdagent, such as an Ubuntu Desktop VM, is the exception. At Both Ways it gets the clipboard through Virtualization's own channel, which sends everything you copy on the Mac, passwords included, even when the VM's window isn't active. Choose another setting to keep them out; the desktop then has no clipboard. This channel doesn't need guest tools: with them off, the setting still decides it, Both Ways or nothing.

Change it in VM Settings → Clipboard, on the Overview tab, or with mvz set <vm> --clipboard both|to-vm|from-vm|off. It applies at once, except on a Linux guest that uses spice-vdagent, where switching to or from Both Ways takes effect at the next restart.

File transfer

Drop files on the VM window, or run mvz send <vm> <file>.

A Linux or FreeBSD guest with several accounts, where none was named when its agent was installed, gets files in /root/MacVisor Transfers, which only root can open. To deliver to a person, run the guest tools installer again with --user <name>.

Files sent from a guest go to your Mac's Downloads folder after you accept them. In Windows, send one with macvisor-agent send <file>; in Linux and FreeBSD, with macvisor-send <file>. MacVisor never overwrites a file, verifies each one before it appears, and quarantines it so Gatekeeper checks it before it first opens. Offers you don't answer are declined after two minutes.

For files you use all the time, a shared folder works better.

Memory reporting

While a VM runs, the Memory card on its Overview shows the memory the guest uses, as its agent reports it ("5.2 GB used in the VM, of 8 GB"), and the guest's memory pressure: Normal, Warning or Critical, in green, yellow or red, as in Activity Monitor. Only the pressure colours the bar.

Below that is what the VM holds on this Mac, such as "8.15 GB held on this Mac". It's normally the VM's whole memory or a little more, because a guest that has run a while has touched all of it (for its caches, say). That's not a sign of trouble.

• The MacVisor Agent reports memory in macOS, Linux, Windows and FreeBSD guests, once it's up to date.
• Linux guests report pressure where the kernel has PSI (/proc/pressure/memory). FreeBSD guests report none. ZFS's cache above its minimum counts as free, as in htop.
• Without an agent that reports memory (none installed, or an older one), the card shows only what the VM holds on this Mac, of its whole memory.
• If the agent misses two readings (about 30 seconds), the card says Guest memory not reported rather than show an old figure: the guest may be busy or short of memory.

mvz show has the same figures, as Memory in use.

QEMU guest agent

Where MacVisor's agent can't be installed, as in many appliances, a QEMU guest agent (qemu-ga) that the guest runs gives MacVisor a little of it: the guest's addresses for mvz ip, <vm>.mvz and the Overview, its system, hostname and kernel, and a clean shutdown. The Guest Tools card then says Limited, with a dark yellow dot, followed by QEMU Guest Agent and its version. Clipboard sharing, file transfer, port forwarding and shells through the agent still need MacVisor's agent, which wins when it connects.

A Linux VM needs QEMU Guest Agent Port on in VM Settings → Guest Tools (mvz set <vm> --qemu-ga on), which new Linux appliances and imported Linux VMs have. A FreeBSD VM has a serial port for it. See QEMU guest agent to set it up.