MacVisor

Quickstart

Make your first VM, in the app or with mvz.

Each section below makes one kind of VM, in the app or in Terminal. Not set up yet? Start with Install and activate.

In the app, a new VM appears in the sidebar as soon as you click Create, with its progress. When it's ready, start it from the library or the Virtual Machine menu; it opens in its own window.

In Terminal, every section follows the same pattern: mvz create makes the VM, mvz wait <vm> --start starts it without a window and returns once it's ready, and mvz shell <vm> signs you in.

A Linux VM

In the app: press ⌘N and choose Linux → Cloud Image and a distribution. Optionally, choose a runtime under Containers and turn on Share my home folder (read-only). Then click Create. The form remembers your choices.

In Terminal:

mvz create ubuntu dev --runtime containerd --home
mvz wait dev --start
mvz shell dev
  • create downloads Ubuntu's cloud image once, verifies it, keeps it as a template, and makes dev as a linked clone of it.
  • --runtime containerd installs containerd with nerdctl, and --home shares your home folder read-only, at the same path. Leave them out and the VM gets neither.
  • wait returns once cloud-init has finished installing the MacVisor Agent and containerd.
  • shell signs you in over SSH as your own user, with your SSH keys. If the folder you're in is shared, the shell opens there.

The account in the VM has no password; you sign in with your SSH key. If create finds no key in ~/.ssh or an SSH agent, it offers to make ~/.ssh/id_ed25519. If you decline, or run it from a script, the VM trusts MacVisor's own key instead: mvz shell and mvz exec work, but plain ssh and editors don't.

Try it:

mvz exec dev -- nerdctl run --rm alpine uname -m   # prints aarch64
mvz ssh-config --install                          # once: then ssh dev.mvz works
ssh dev.mvz

After mvz ssh-config --install, plain ssh, scp and VS Code Remote-SSH reach your cloud-image and macOS VMs by name. Ports the guest listens on appear on the Mac's localhost at the same number, with a few exceptions, and http://dev.mvz:8080 reaches the guest directly.

Docker instead:

mvz create ubuntu web --runtime docker
mvz wait web --start
docker --context macvisor-web ps

create makes the macvisor-web docker context when the docker command is on the Mac. If it isn't installed yet, or you made the VM in the app, run mvz docker web.

A desktop: for Ubuntu, turn on Install Ubuntu Desktop in the form's Account section. The first boot then takes 10 to 20 minutes longer, and the VM's window shows the desktop. See Ubuntu Desktop.

Other distributions, and what cloud-init sets up, are in Cloud images and macOS installers.

Linux from an ISO

In the app: press ⌘N, choose Linux → Installer ISO, select an ARM64 ISO, and click Create. MacVisor attaches the ISO as USB storage and boots the installer in the VM's window.

In Terminal:

mvz create ~/Downloads/archlinux-aarch64.iso arch --os linux --start

--start opens the VM's window, to install in. The default disk settings suit most installers; see Disk formats if yours needs others. After you install to the disk:

  1. Eject the ISO. MacVisor offers to when the VM first stops, or use VM Settings → Storage or mvz set arch --iso none.
  2. Install the MacVisor Agent by hand.

The VM's window has a Display | Console switch. Sign in at the console with the account you made in the installer, or open it in Terminal with mvz console arch. See Display and console.

A macOS VM

In the app: press ⌘N, choose macOS, pick an installer or a local .ipsw, keep or change the account, and click Create & Install.

In Terminal:

mvz create macos-27 mac --ssh
mvz wait mac --ssh --start
mvz shell mac

create downloads Apple's macOS 27 installer once, verifies it, and installs it into a new VM. This takes 20 to 30 minutes; follow it in the task pane or with mvz tasks. --ssh on create turns on Remote Login in the guest; on wait, it waits until SSH answers.

On first boot, the VM creates the account macvisor with a random password (mvz password mac prints it) and signs in. MacVisor then installs the MacVisor Agent and authorizes your SSH keys, so shell needs no password. This step needs the Local Network permission.

A macOS 27 VM window next to its Overview tab, with MacVisor Agent installed.

macos-latest installs the newest macOS this Mac supports. Guests older than macOS 27 go through Setup Assistant by hand. See Create VMs and templates.

A Windows 11 VM

First download Windows 11 on ARM from Microsoft. Windows VMs need macOS 27.2.

In the app: press ⌘N, choose Windows, and select the ISO. To use mvz shell, turn on Enable Remote Login (SSH) under More Options. Click Create & Install.

In Terminal:

mvz create ~/Downloads/Win11_26H2_English_Arm64.iso win11 --ssh
mvz wait win11 --start
mvz open win11

create installs Windows unattended in about 10 minutes. It accepts Microsoft's license terms for you, leaves Windows unactivated, and sets up the account macvisor with a random password (mvz password win11 prints it), Remote Desktop, the MacVisor Agent and, with --ssh, OpenSSH Server with your keys.

open shows the VM's window, sharp at any size, with sound and a microphone. mvz shell win11 opens PowerShell over SSH, and mvz rdp win11 opens the VM in Microsoft's Windows App. What works and what doesn't is in Windows 11 guests.

A FreeBSD VM

In the app: press ⌘N, choose FreeBSD, and click Create.

In Terminal:

mvz create freebsd bsd
mvz wait bsd --start
mvz shell bsd

The first boot takes 2 to 5 minutes. FreeBSD has no display after its loader, so its window shows the console: sign in there with the password mvz password bsd prints. See FreeBSD guests.

Next steps

  • Take a snapshot in the VM's Snapshots tab, or with mvz snapshots take dev --name baseline. A running VM's snapshot includes its memory, so reverting resumes where you were. A disk-only one (--disk-only) is the safer baseline: a live snapshot's memory may not restore after a MacVisor or macOS update. See Snapshots and recovery.
  • Reuse a VM. Convert to Template turns a VM you've prepared into a base for new ones, and Linked Clone… forks a VM in seconds without copying its disk. See Linked clones.
  • Bring VMs from another app with File → Import… (⇧⌘I) or mvz import --scan. See Import VMs from other apps.
  • Clean up. mvz stop dev shuts a VM down, and mvz rm dev moves it to the Trash, as Move to Trash… does in the app.
  • Learn the CLI. mvz list, mvz show dev and mvz help create. A VM can be named by its name, its id, or the first 4 or more characters of its id. See Using the CLI.
  • Find your way around the app in The MacVisor interface.