VM settings reference

VM Settings groups its pages in the sidebar: Machine (General, System, Advanced), Devices (Display, Keyboard & Pointer, Sound, Storage, Network), and Integration (Guest Tools, Clipboard, Cloud-Init on Linux VMs made from a cloud image, and Shared Folders). Each page opens with a summary of what's attached, and device rows show a dot: green while the running VM uses the device, grey when the VM isn't running, orange when something is missing (a folder, an image, a network). Before saving, MacVisor says when your edits apply: now, or at the next start. On a suspended VM, port forwards and the clipboard direction apply when it resumes.

General

Identity: name, icon, and up to 256 characters of notes shown on the Overview tab.

Startup: Start at Login has the background service start the VM headless at each login, whether or not the MacVisor app opens. A VM shut down at logout, the default, boots fresh; with Suspend VMs chosen in Settings -> General -> Logout and Shutdown, it resumes from its saved state, once the Mac is unlocked if it is locked. See Always-on host.

Window: what closing the VM window does (When the Window Closes: Hide Window, Ask Each Time, or Shut Down VM), and whether the VM opens in its own window by default.

System

Resources: vCPU count and memory. Both apply at the next start from shut down; a suspended VM resumes with the earlier values first.

Performance: the memory balloon, and nested virtualization on an M3 or later Mac. Both are on by default for Linux VMs made from a cloud image. A running VM's balloon target is set in GiB on the Overview tab or with mvz set <vm> --balloon-target <GiB>. It stays between the VM's memory and a floor: a quarter of the memory, and at least 1 GiB (4 GiB for a macOS guest). Below half the memory, the Overview asks first.

Firmware (Linux): Secure Boot boots only signed kernels; shim-signed distributions work. Turning it off keeps the enrolled keys.

Rosetta (Linux): mounts Rosetta into the guest so it can run x86-64 Linux binaries.

Display

• Headless removes the graphics device, for servers and automation.
• Accelerated Graphics uses Apple's Mac graphics device; macOS guests only. Linux guests use software-rendered Virtio graphics.
• When the Window Resizes: Change the Guest's Resolution (the guest follows the window, on macOS 14 or later and on Linux display drivers that support it) or Scale to Fit, Keep the Resolution (the guest keeps the resolution below and the window scales it).
• Primary Display: a preset (1080p, 1440p, 4K, Studio Display 5120x2880, Classic 1920x1200) or a custom resolution and PPI.
• Additional Displays: not available yet. A macOS VM that already has extra displays lists them here only so you can remove them: no window shows them, and each leaves a blank display in the guest.

Storage

Boot Disk: file name, capacity, and format. The format is not editable: MacVisor creates ASIF and keeps legacy raw disks as they are.

• Resize... grows an ASIF disk, and on a macOS guest also shrinks it. A Linux guest's disk and a layered (linked-clone) disk only grow. On a raw disk the button is Expand... and only grows. A template's disk can't be resized while VMs made from it read it. mvz set <vm> --disk <GiB> grows from the CLI; a cloud-image Linux VM grows its filesystem at the next boot. See Resizing.
• Convert to ASIF... appears for a raw disk on a stopped VM. See Storage and sharing for the free-space rule.
• Bus: Virtio or NVMe, plus caching and synchronisation policy.

Additional Disks: create, attach, resize, or remove extra ASIF images. Removing one moves its image to the Trash. Disk changes need the VM shut down, with no suspended session; the section says what is in the way.

Disk Images: ISOs and raw images attached by path on a chosen bus at the next start. USB-bus images can also be attached while the VM runs, here or on the Overview tab, when Allow Attaching USB Images While Running is on. Compressed or sparse .dmg files are not supported.

Network

Network Adapters lists the VM's adapters (up to four), each expanded by default. A row shows the adapter's mode and status, what it connects to (the bridged interface or the custom network), and its address while the VM runs; on a running VM, Reconnect and the Connected switch are on its right (switching it off unplugs the cable in the guest). Under it: MAC address, mode (NAT, bridged with the host interface to use, or a custom network), and, for an extra adapter, Remove This Adapter. Add Network Adapter adds one.

Host port forwarding: per-VM TCP or UDP forwards from a host address and port to a guest port, through the guest agent. They apply at once to a running VM with guest tools connected, and to a suspended VM when it resumes. A cloud-image VM also forwards the ports its guest listens on automatically, to 127.0.0.1 at the same number.

See Networking and Custom networks.

Cloud-Init

Linux VMs made from a cloud image only. It shows what cloud-init was given for the first boot: hostname; account (user name, full name, and the UID mirrored from your Mac account); container runtime; whether to install the guest agent; the SSH authorised keys, one per line; and your own user data, applied after MacVisor's.

Editing these after the first boot changes what a re-provisioned guest would get, not the guest you have. To re-provision, turn on Set up again on next start: the next boot runs cloud-init as for a new machine, with a new identity (and possibly a new address).

Shared Folders

Share Folders with the Guest turns sharing on or off as a whole: off detaches every folder at the next start and keeps the list and each folder's permissions for when you turn it back on.

A table of the Mac folders the guest can use, each with a Permissions menu: Read Only or Read & Write. Click + to share a folder, select one and click - to stop sharing it. A cloud-image Linux VM's agent mounts them at the same path in the guest at every boot; a macOS guest shows them in Finder under My Shared Files. Permission changes apply at the next start from shut down.

Clipboard

Which way the clipboard is shared: Both Ways (the default), Mac to VM Only, VM to Mac Only, or Off. Text and images only; the Mac's clipboard is sent only while the VM's window is active. Applied live, except on a Linux guest using spice-vdagent, where a change to or from Both Ways applies at the next restart. The Overview tab has the same picker, and mvz set <vm> --clipboard both|to-vm|from-vm|off sets it from the CLI. See Guest tools.

Guest Tools

Enable Guest Tools turns on the host side of the agent channel; Attach Guest Tools Image at Boot mounts the MacVisor Agent volume at each start. Agent Channel: the Guest Agent Channel (vsock) device the tools use (leave it on), and the transport the agent prefers (Automatic suits every normal case). Guest tools add devices to the VM, so turning them on or off, here or with the Overview's Guest tools switch, applies at the next start from shut down; a suspended VM resumes as it was saved. See Guest tools.

Guest-initiated file, URL, and port-forward requests always need your approval, whatever these settings say.

Keyboard & Pointer

A Mac keyboard and Mac trackpad for macOS guests; a USB keyboard and pointing device stay attached as a fallback.

Input Capture: Send System Shortcuts to the Guest sends shortcuts such as ⌘Tab to the guest; Control-Command or Control-Option hands control back.

Sound

Output and input are separate Virtio devices. Microphone input asks for macOS microphone permission the first time the guest listens.

Advanced

Automatic Setup (first boot): macOS 27 guests: create the first account (mac / macvisor by default; the New VM form remembers the account name you used last, not the password), sign it in automatically, and turn on Remote Login, skipping Setup Assistant. With Remote Login on, MacVisor installs the guest agent after the first boot, authorises your SSH keys, and then turns SSH password logins off. Ignored once the guest has been set up.

NVRAM: a shut-down macOS guest's NVRAM variables, such as boot-args (-v for a verbose boot). A wrong value can keep the guest from booting. macOS 27 currently refuses the private interface this uses; the section says so, as does mvz nvram <vm>, and MacVisor stops trying until macOS is updated. Where it works, a change is written to a copy of the NVRAM first and kept only if it completes, so a failed change leaves the variables as they were.

USB: devices to capture automatically when plugged in while the VM runs; or connect one on demand from the USB button in the VM window.

Devices

Toggling a device changes the VM's topology: it applies at the next start from shut down, and a suspended VM resumes with the devices it was saved with.