MacVisor

VM settings reference

Every VM setting, the page it lives on, and when a change takes effect.

A VM's Settings tab groups its pages under Machine (General, System, Advanced, Backup), Devices (Display, Keyboard & Pointer, Sound, Storage, Network) and Integration (Guest Tools, Clipboard, Cloud-Init, Shared Folders, AI Agents).

Each device has a status dot: green when in use, grey when the VM is off, orange when something it needs is missing.

Saving and undoing

VM Settings saves every change by itself; there's no Save button. A switch, picker or slider saves a moment after you change it, and a text field a second after you stop typing, or when you press Return or Tab. Whatever is waiting is saved when you change page, select another VM, leave Settings, close the window or quit. Start, Restart, Resume, Clone, New VM from Template and Take Snapshot save the VM's changes first.

The footer says All changes saved, Saving…, or why a change couldn't be saved, with Retry. A value that can't be saved as typed, such as an empty or taken name, says why in its field, and the rest still saves. The footer also names the changes that apply only at the next start.

Undo Last Change, in the footer, puts back the last change on the page you're on. It shows only while that page has a change of its own to undo. Click it again to go further back. A burst of changes to one setting, such as typing in a field or dragging a slider, is one change. A setting changed again since, here or with mvz, keeps its newer value. Removing a network adapter, a shared folder or a saved automatic setup asks first.

When changes apply

  • Hardware (CPUs, memory, network adapters, displays, devices) changes at the next start from shut down. A suspended VM resumes with its old hardware first, because its saved memory depends on it.
  • Disks can't change while a session is saved. Discard it first with Start from Disk…, Discard Saved State or mvz set <vm> --disk <GiB> --discard-state.
  • Port forwards, the clipboard direction, and a Windows VM's pixel density and visual effects apply at once, or when a suspended VM resumes.

On a running VM, each page says at the top which of its changes apply now:

PageApplies nowAt the next start
GeneralEverything
BackupEverything
AI AgentsEverything
ClipboardEverything, except in a Linux guest that uses spice-vdagentThe clipboard of a Linux guest that uses spice-vdagent
Display, Windows VM with a windowPixel Density (on Virtio-MVZ) and Reduce Visual EffectsThe rest
NetworkPort forwards, and each adapter's Connected switch (remembered for the next start too)Other changes to the adapters
Every other pageEverything

General

  • Name, icon and notes. Pick one of MacVisor's icons, or Choose Image… to use a picture of your own (PNG, JPEG, HEIC, TIFF, SVG or PDF); Use Default goes back to the icon of the VM's system. MacVisor keeps a copy of the picture in the VM, so it stays when you copy, move or export the VM. Notes (up to 256 characters) show on the Overview tab. A new VM's start with its installation info.
  • Start at Login. The background service starts the VM at each login, even if the app doesn't open. A suspended VM resumes. At Login says how: Start in the background (the default) or Start and open its window. A VM with it on carries an AUTO badge in the VM list and AUTO-START beside its name on the Overview. See Always-on host.
  • High Availability. The background service starts the VM again when it crashes, stops with an error or fails to start: 5 s after the first stop, then 15, 30, 60, 120 and 300 s between tries (a VM that had run for ten minutes before it stopped starts the delays afresh, at 5 s), and no more than ten restarts in an hour, after which it stays stopped until you start it yourself. A VM you shut down, power off or suspend, from MacVisor or from inside the guest, stays stopped. Independent of Start at Login: it watches the VM from the moment it runs. The Overview's events show each restart. Also mvz ha <vm> on, and for every VM at once in Settings → VMs. A VM with it on carries an HA badge in the VM list and HIGH AVAILABILITY beside its name on the Overview. See High availability.
  • VM Watchdog, under High Availability and shown while it's on: restarts the VM when its guest stops responding, as MacVisor's guest agent reports it. It needs the agent in the VM. Sensitivity: Normal, after 10 minutes, at most 3 restarts a day, or Low, after 30 minutes, at most 1 a day. Off by default. See VM Watchdog.
  • Protect from Deletion. While it's on, nothing can move the VM or template to the Trash or erase it: not the app, mvz (with --yes or not), an AI agent over MCP or the AI sandbox tools. Move to Trash… and Erase and Install… are turned off for it, with a tooltip saying why, and so is Remove Disk on the Storage page; the Delete key says why instead. Moving several VMs to the Trash leaves the protected ones where they are. To delete the VM, turn the switch off first, here or with mvz protect <vm> off. Agents can't turn it on or off. It goes with the VM when you export, back up, import, restore or move it, and a revert keeps it as it is now. A clone or copy, and a VM made from a protected template, starts without it. Off by default, and saved at once. Also mvz protect <vm> on. Right after an update, while MacVisor's background service still runs the older build, turning it on is refused: quit and reopen MacVisor, then try again.
  • When the Window Closes: Hide Window, Ask Each Time or Shut Down VM.

System

SettingNotes
vCPUs, memory
Memory balloonLets MacVisor reclaim memory from a running guest. On by default for cloud-image Linux VMs.
Nested virtualizationLets the guest run KVM. M3 or later. On by default for cloud-image Linux VMs.
RosettaLinux. Runs x86-64 Linux programs.

Windows VMs support neither the balloon nor nested virtualization.

Set a running VM's balloon target on the Overview tab, or with mvz set <vm> --balloon-target <GiB>. The floor is a quarter of the VM's memory and at least 1 GiB, or 4 GiB for macOS. MacVisor asks first if you go below half.

Firmware

On the System page, for Linux and Windows VMs. Not for FreeBSD VMs, whose boot loader isn't signed, or macOS VMs.

SettingNotes
Secure BootLinux: boots only signed kernels, which shim-signed distributions provide. Windows: starts only signed boot files, Windows' and MacVisor's; on for new Windows VMs. Also mvz set <vm> --secure-boot on|off. See TPM and Secure Boot.
TPMA TPM 2.0 whose keys stay with this Mac. Windows: on for new Windows VMs, for BitLocker, Windows Hello and the Windows 11 checks. Linux: off until you turn it on. See A TPM for Linux VMs. Turning it off keeps the TPM for when it's on again. Also mvz set <vm> --tpm on|off.
Boot FilesWindows. Repair Boot Files writes MacVisor's boot files to the VM's EFI partition again, for a VM that stops right after it starts. Also mvz repair-boot <vm>.
TPM KeysReset TPM… erases the VM's TPM, after asking: the VM gets a new one at its next start, and what was sealed to the old one is lost. Also mvz tpm reset <vm>. See Reset the TPM.

Secure Boot and TPM changes apply at the next start from shut down. Repair Boot Files and Reset TPM… need the VM shut down, with no suspended session. Turning Secure Boot or the TPM on for a Windows VM made by an earlier MacVisor puts MacVisor's current signed boot files on its EFI partition, so shut it down first. To take a VM's TPM to another Mac, use mvz tpm export and mvz tpm import: see Move or reset the TPM.

A TPM for Linux VMs

Turn on TPM under Firmware, or run mvz set <vm> --tpm on. A Linux VM boots through its distribution's own shim and GRUB, so MacVisor's guest agent puts MacVisor's TPM driver on the guest's EFI system partition, as \EFI\MacVisor\mvtpm.efi, and registers it as a UEFI driver with efibootmgr --driver. From the VM's next start the guest has a TPM 2.0: /dev/tpm0 and /dev/tpmrm0, through the kernel's tpm_crb driver, with the firmware's measured-boot log in /sys/kernel/security/tpm0/binary_bios_measurements.

It needs:

  • MacVisor's guest agent in the VM. Cloud-image VMs have it; install the guest tools in others.
  • efibootmgr in the guest.
  • The EFI system partition mounted at /boot/efi, /efi or /boot.

With Secure Boot on, MacVisor adds its certificate to the VM's db, so the firmware loads the driver. If the agent can't install the driver, the VM's runner log says why.

It's tested on Ubuntu 26.04, where systemd-analyze has-tpm2 says yes. Use it with systemd-cryptenroll --tpm2-device, systemd-creds and tpm2-tools.

The TPM is sealed to this Mac, and Reset TPM, mvz tpm export and mvz tpm import work as for Windows. A reset erases what was sealed to the TPM, such as a LUKS key enrolled with systemd-cryptenroll, so keep the volume's passphrase or recovery key.

Display

SettingNotes
HeadlessNo display and no window, for servers and automation. Reach the VM over SSH or mvz console. See VMs without a window.
DisplayWindows VMs only: Virtio-MVZ, MacVisor's own display device, or Apple. See below.
Pixel DensityWindows VMs on MacVisor's display. Automatic (2× up to 4K), the default: the screen's own pixels until the guest's display would pass 4K's worth, and fewer in larger windows, which the window scales up (set Windows' scaling to about 150% in a large window). Retina (2× pixels): always the screen's own density, the sharpest and the most CPU (set Windows' scaling to 200%). Standard (1× pixels): one pixel per window point. Applies live. See The display.
Reduce Visual EffectsWindows VMs. Turns off Windows' transparency and animations, which it draws with the Mac's CPU. On for new Windows VMs. The MacVisor Agent applies it once for each Windows user, so a later change in Windows' own Settings stays. Applies live. See Visual effects.
Accelerated GraphicsmacOS guests only. Linux and Windows use software-rendered graphics.
When the Window ResizesChange the Guest's Resolution to follow the window (macOS 14 or later, and Linux drivers that support it), or Scale to Fit, Keep the Resolution. New macOS, Windows and Ubuntu Desktop VMs change the resolution.
Resolution1080p, 1440p, 4K, Studio Display (5120x2880), Classic (1920x1200), or a custom resolution, with a PPI for a macOS guest. Shown only for a VM whose resolution doesn't follow its window, since that is the only one with a size of its own.
Additional DisplaysNot supported yet. Existing extra displays on a macOS VM are listed only so you can remove them.

Windows VMs have a Display choice: Virtio-MVZ, MacVisor's own display device, on which Windows takes any resolution and follows the window (Change the Guest's Resolution is on for new Windows VMs), or Apple, Apple's device, on which Windows draws only 1024 x 768, scaled to fit. The choice applies at the next start from shut down; a suspended VM or a live snapshot resumes with the display it was saved with. See The display.

Storage

SettingNotes
Boot DiskName, capacity, format and sector size. New disks are ASIF unless you chose Raw for a Linux ISO install. Raw disks stay raw until you convert them.
Resize…Grows a disk. A macOS guest's ASIF disk can also shrink: Shrink… checks where the disk's partitions end and refuses a size they don't fit in, asks first, and takes a snapshot before it shrinks. On a raw disk the button is Expand….
Convert to ASIF…For a raw disk on a stopped VM.
BusVirtio or NVMe, with caching and sync options.
Additional DisksAdd, resize or remove disks. Add Disk takes a Format (ASIF or Raw) and, for ASIF, a Sector Size: 512 bytes (the default) or 4 KB (native). Removed disks go to the Trash, or are deleted on a drive with no Trash, such as a network share; the question says which.
Disk ImagesISOs and raw images, attached at the next start. With Allow Attaching USB Images While Running on (the default), you can also attach an image to the running VM as a read-only USB drive, until it stops. With it off, every such attach is refused, from the app, mvz and agents alike. See Disk images on a running VM.

See Disk formats and sector sizes for what ASIF, raw and the sector sizes mean. Disk changes need the VM shut down without a saved session. A template's disk can't be resized while VMs use it. A cloud-image Linux VM grows its filesystem at the next boot after a resize. Compressed or sparse .dmg files can't be attached. See Resizing.

Network

A VM can have up to four Network Adapters. Each has a MAC address and a mode: NAT, bridged to a Mac interface, or a custom network. Each adapter's Connected switch plugs and unplugs its virtual cable, like pulling out an Ethernet cable: at once on a running VM, and it's remembered, so an unplugged adapter stays unplugged when the VM starts again, until you switch it on. Use it to keep a VM you're testing or retiring off the network, even if someone starts it by accident. The adapter's row says Unplugged (Disconnected means it's out without your say: its bridged interface is down or its network is gone). On a running VM, Reconnect plugs it in again on the network below.

Host Port Forwarding maps a port on this Mac to a guest port, over TCP or UDP. Forwards listen on this Mac only (127.0.0.1, and ::1), and MacVisor's guest agent carries each connection to the guest's localhost, so the network firewall doesn't apply to them. Cloud-image Linux VMs also forward listening ports automatically. To reach the VM from other devices, use a custom network's port forwarding or a bridged network. See Port forwarding.

See Networking and Custom networks.

Cloud-Init

Linux VMs made from a cloud image or disk image, appliances included. Shows what cloud-init used on the first boot: hostname, account, runtime, agent, SSH keys and your user data. Edits don't change the existing guest. To apply them, turn on Set up again on next start: the guest is set up as a new machine, with a new identity and possibly a new address.

Set up with cloud-init comes first. Turn it off for an image that has no cloud-init, such as a router or firewall made with the switch on by mistake. From the next start the VM is an appliance: no seed disk, setup status or SSH checks, and the Overview shows the Appliance card. Guest tools stay as they are; a FreeBSD VM gets its agent's token on a small disc of its own. The page then holds only the switch.

Turn it back on to bring back the setup as it was. The instance id stays the same, so cloud-init doesn't set the guest up again.

The switch applies at once, and only while the VM is shut down (not suspended). Templates and AI sandboxes can't use it, and a VM made without cloud-init has no setup to turn on.

Shared Folders

List Mac folders for the guest, each Read Only or Read & Write. Use + and - to add and remove them. A cloud-image Linux VM mounts each at the same path. A macOS guest shows them in Finder under My Shared Files. Changes apply at the next start from shut down.

Share Folders with the Guest turns all sharing off or on and keeps the list.

Clipboard

Both Ways (the default), Mac to VM Only, VM to Mac Only or Off. Text and images are shared. The Mac's clipboard is sent only while the VM window is active, and what you copy in the VM comes to the Mac when you leave its window. A headless or hidden VM never sets the Mac's clipboard. Also on the Overview tab, and in mvz set <vm> --clipboard both|to-vm|from-vm|off. With guest tools off, only a Linux guest running spice-vdagent shares the clipboard, at Both Ways. See Guest tools.

Guest Tools

Enable Guest Tools connects the Mac to the MacVisor Agent. Attach Guest Tools Image at Boot mounts the agent installer at each start. Leave MacVisor Agent Channel (vsock) on. QEMU Guest Agent Port (Linux VMs) is for a QEMU guest agent the guest ships, as Home Assistant OS and other appliances do; both can be on. Changes apply at the next start from shut down.

To attach or eject the disc for one run only, without changing these settings, use Attach Guest Tools or Eject Guest Tools on the Overview. See The guest tools disc.

  • QEMU Guest Agent Port, Linux VMs only, adds the port a QEMU guest agent in the guest uses. It's on for new Linux appliances and Linux VMs imported from other apps. Also mvz set <vm> --qemu-ga on|off.
  • FreeBSD VMs: Enable Guest Tools gives the VM MacVisor's agent, which MacVisor installs over SSH; restart the VM after turning it on. There is no disc at boot. See The MacVisor Agent on FreeBSD.

File, URL and port-forward requests from the guest always need your approval. See Guest tools.

AI Agents

What AI agents connected to MacVisor's MCP server (mvz mcp serve) may do with this VM:

  • Off (the default): nothing. Agents don't see the VM.
  • View: see its state and details, take screenshots, list its snapshots, and read its files.
  • Control: also start, stop and suspend it, run commands, write files, attach disk images, take snapshots and revert to them (a safety snapshot is taken first), and use its keyboard and pointer.

On a template, any level lets agents make VMs from it. Connect Agents… opens Settings → AI → Agent Access, where you add MacVisor to Claude Code, Codex, Cursor and other agent apps. The page also says when an agent made the VM, and lists the latest things agents did with it. A change applies at the agent's next request. Copies and imports start at Off, and a revert keeps the current level. Also mvz set <vm> --agents off|view|control. See AI agents and MCP.

Backup

Scheduled backups of the VM to a folder of your choice, off by default: Back Up Automatically, Folder, Frequency (Daily or Weekly, with a Day), Time, and Keep the newest (7 by default). Back Up Now makes one at once, and Status shows the last and the next backup. Changes apply at once, also while the VM runs. Templates have no Backup page. Also mvz set <vm> --backup … and mvz backup <vm>. See Backups.

Automatic Snapshots, on the same page: Take Snapshots every hour, day or week while the VM runs, keeping the last 24, 7 or 4 unless you change it (1 to 30). Off by default. Also mvz set <vm> --auto-snapshots hourly|daily|weekly. See Automatic snapshots.

Keyboard & Pointer

macOS guests get a Mac keyboard and trackpad, with a USB keyboard and mouse as a fallback.

Keyboard in the VM is the keyboard layout the VM uses, which Type Password and Type Clipboard type for. U.S. types as on a U.S. keyboard, whatever your Mac uses: right for Linux, new macOS VMs and Windows installed from an English (United States) ISO. Same as This Mac types with your Mac's current layout: choose it when the VM uses the same layout as your Mac. It applies at once, also while the VM runs.

A Windows, Linux or FreeBSD VM on Same as This Mac uses the PC version of the layout, which puts some characters on other keys than the Mac's. So Type Clipboard types into it only what both have on the same keys: from a U.S. or ABC layout on the Mac, every character a U.S. keyboard types; from any other layout, letters and digits, spaces, tabs and line breaks. For a VM whose keyboard is U.S., choose U.S. to type everything.

Until you choose, Linux and macOS VMs use U.S. MacVisor records the language of the ISO it installed Windows from, and Windows gets that language's keyboard. A Windows VM uses U.S. only for English (United States), and Same as This Mac for any other language, including English (United Kingdom), and for a Windows VM installed by an earlier MacVisor, which didn't record it. If you choose U.S. for a Windows VM installed with another keyboard, the caption says which.

Sound

Separate output and input devices. New macOS and Ubuntu Desktop VMs have the microphone; macOS asks for permission the first time a guest listens. A new Windows VM's page has Sound and Microphone for MacVisor's audio device; both apply at once, even while the VM runs, and Microphone is unavailable while Sound is off. A Windows VM made by an earlier MacVisor has the page only if it was made with sound. See Sound.

Advanced

Automatic Setup (first boot) creates and signs in the first account on a macOS 27 guest, skipping Setup Assistant. The Overview's macOS VM card shows it as the setup account, with its password buttons. See Create VMs and templates.

NVRAM doesn't work on macOS 27, and the page says so. Set boot-args from Terminal in recoveryOS instead.

USB Devices lists the VM's remembered USB devices. Remove Device (the minus button) stops MacVisor attaching one; a device attached now stays attached until the VM stops. They're attached whenever the VM runs and they're plugged in, with its window open or not. Remember one with the USB button in the VM's window, or with mvz usb remember. See USB devices.

Health Check is a command that exits 0 while the VM is healthy, run On This Mac or In the VM every Interval seconds (30 to 3600, 60 by default), with Test. Restart the VM when it keeps failing restarts the VM after 20 minutes of failures on this Mac, or 10 in the VM, at most once a day and never while you're using its window; High Availability doesn't need to be on. When It Fails, Run is a command run on this Mac when the check has failed. See Health checks.

Hooks are commands run on this Mac, as you: Shutdown Command (runs instead of MacVisor's own shutdown for this VM; Power Off doesn't use it), After the VM Starts and After the VM Stops, each with Test. They're kept on this Mac, not in the VM. Templates and AI sandboxes have none. See VM hooks.

Devices: Random Number Generator gives the guest a hardware entropy source. Serial Console writes the guest's serial output to console.log in the VM folder, rotated at 16 MiB, and mvz console and View → Show Console in the VM's window attach to it. It is on by default for new Linux VMs, always on for FreeBSD VMs, whose console it is, off by default for macOS VMs, and not available for Windows VMs. See Display and console.