MacVisor ships a catalogue of Linux cloud images, FreeBSD images and macOS installers. Name one, such as ubuntu, debian-13 or macos-27, and MacVisor downloads it once, verifies it, and keeps it for every VM you make from it. The sidebar's Templates section and mvz images show the same catalogue.
Linux images
All images are ARM64. Use the id or any alias with mvz create and mvz images pull.
| Image | Id (aliases) | Source | Build |
|---|---|---|---|
ubuntu-26.04 (ubuntu, ubuntu-lts) | cloud-images.ubuntu.com | Tracks the vendor's newest build | |
ubuntu-24.04 | cloud-images.ubuntu.com | Tracks the vendor's newest build | |
debian-13 (debian) | cloud.debian.org | Tracks the vendor's newest build | |
debian-12 | cloud.debian.org | Tracks the vendor's newest build | |
fedora-44 (fedora) | download.fedoraproject.org | Fixed build, 44-1.7 | |
fedora-43 | download.fedoraproject.org | Fixed build, 43-1.6 | |
rocky-10 (rocky) | dl.rockylinux.org | Tracks the vendor's newest build | |
rocky-9 | dl.rockylinux.org | Tracks the vendor's newest build | |
almalinux-10 (alma, almalinux) | repo.almalinux.org | Tracks the vendor's newest build | |
almalinux-9 | repo.almalinux.org | Tracks the vendor's newest build | |
oraclelinux-10 (oracle, oraclelinux) | yum.oracle.com | Fixed build, 10 Update 1 | |
oraclelinux-9 | yum.oracle.com | Fixed build, 9 Update 8 | |
centos-stream-10 (centos, centos-stream) | cloud.centos.org | Tracks the vendor's newest build | |
opensuse-leap-16.1 (opensuse, leap) | download.opensuse.org | Tracks the vendor's newest build | |
alpine-3.24 (alpine) | dl-cdn.alpinelinux.org | Fixed build, 3.24.4 | |
kali-2026.3 (kali) | kali.download | Fixed build, 2026.3 |
"Tracks" entries download the vendor's current build. Fixed builds move forward with MacVisor updates.
Kali's cloud image has no desktop. For one, turn on Install Kali Desktop (Xfce) in the New VM form's Account section: the first boot installs Kali's Xfce desktop, takes about 5 minutes longer and restarts once, and your account signs in to it by itself. The switch is in the app only.
FreeBSD
| Image | Id (aliases) | Source | Build |
|---|---|---|---|
freebsd-15 (freebsd) | download.freebsd.org | Tracks the vendor's newest build | |
freebsd-16-snapshot (freebsd-current) | download.freebsd.org | Tracks FreeBSD's weekly development snapshot, which may break |
Both images are FreeBSD's ARM64 BASIC-CLOUDINIT builds with a UFS root, checked against FreeBSD's SHA-256 lists. A FreeBSD image downloaded now is named FreeBSD 15.1; one downloaded before keeps (Experimental) in its name until you rename it.
mvz images pull freebsd
mvz create freebsd bsd # or: mvz create freebsd-current bsd16
mvz start bsd --headless
mvz wait bsd --ssh
mvz shell bsd
A FreeBSD VM is used over SSH and at its console, where your account signs in with a password, and MacVisor installs its agent over SSH after the first boot, which takes 2 to 5 minutes. FreeBSD guests has the whole story: creating one, the console and its password, MacVisor's agent over a serial port, the QEMU guest agent, the power button, and FreeBSD VMs made before.
These sections are now on their own page: Sign in, The console, Shut down and restart, MacVisor's agent and FreeBSD VMs made before.
Not available on FreeBSD
FreeBSD has no virtio-fs, and its agent does less than the Linux one. FreeBSD VMs don't have:
- A display after FreeBSD's loader: the window shows the console instead.
- An installer ISO: make the VM from the catalogue or a disk image.
- Clipboard sharing, shared folders or container runtimes.
mvz createrefuses--homeand--runtime. - Automatic port forwarding. Add forwards yourself (with the agent), or reach the VM as
<vm>.mvz. - Fixed addresses: a reservation may not apply.
- Rosetta and Free Unused Space.
Appliances: images without cloud-init
A router, firewall or other appliance image (OpenWrt, VyOS, pfSense-based, OPNsense-based, armsense) has no cloud-init. Make a VM from it without cloud-init: in the New VM form, choose Linux, or FreeBSD for a FreeBSD-based image (pfSense-based, OPNsense-based, armsense), then Image File or URL…, and turn off Set up with cloud-init. From the CLI, pass --no-cloud-init, and --os freebsd for a FreeBSD-based image.
mvz networks create lan --host-only
mvz create ~/Downloads/armsense.qcow2 router --no-cloud-init
mvz nics add router --network lan
mvz start router --headless
mvz ip router --wait
MacVisor boots the image as it is. It attaches no cloud-init seed, makes no account, authorises no SSH keys, and installs no agent, container runtime, shared folders or Rosetta. Set the appliance up through its own web UI or console. The template made from the file or URL remembers the choice, so later VMs from it are appliances too, unless you turn the switch back on or pass --cloud-init. The catalogue's Linux images are set up with cloud-init unless you say otherwise; its appliances, below, never are.
A new appliance, from the catalogue or a file, starts with Auto-start and High Availability on, and nested virtualization and the memory balloon off. Change them in VM Settings afterwards.
- Guest tools. A new Linux appliance gets guest tools as a VM installed from an ISO does: the guest tools disc at each start, and the agent's channel. If the appliance lets you install software, install the agent from the disc for clipboard sharing, file transfer, port forwarding and a clean shutdown. A new Linux appliance also gets a port for a QEMU guest agent, which images such as Home Assistant OS run. A FreeBSD-based appliance has guest tools off and no disc at start. Turn on Enable Guest Tools in its settings and it gets a small disc with the agent's token at each start; then attach the guest tools disc and, as root, run
mount -t cd9660 /dev/iso9660/MACVISOR_AGENT /mnt && sh /mnt/install-freebsd.sh, if the appliance lets you install software. Appliances made with an earlier MacVisor keep their settings. - FreeBSD-based appliances (pfSense-based, OPNsense-based, armsense) boot through the same MacVisor boot volume as FreeBSD VMs.
- WAN. The first adapter is the appliance's WAN, except in OpenWrt, whose first adapter is its LAN (see Appliances in the catalogue). Leave it on a MacVisor network, such as the Default MacVisor Network, so the appliance gets an address and reaches the internet through the Mac.
- LAN. Put a LAN adapter on a host-only network, with
mvz nics add <vm> --network <network>or in VM Settings → Network. Never bridge it to a network that has its own DHCP server or uses the same subnet: the appliance's DHCP server would answer there too. - Reaching the LAN from the Mac. The Mac reaches the appliance on a host-only network only at an address inside that network's subnet, which macOS chooses (
mvz networksshows it). macOS 27.2 can't pin a host-only network to 192.168.1.0/24, so an appliance whose LAN is 192.168.1.1 can't be reached there: give its LAN an address in the network's subnet, or have its LAN get one from the network by DHCP (with its own DHCP server off there). pfSense-based images block their web UI on the WAN side. - Addresses.
mvz ip, the Overview and<vm>.mvzshow the addresses the appliance's agent or QEMU guest agent reports, else those the Mac has seen it use (DHCP leases and ARP), never a network's reservation.<vm>.mvzanswers with the first adapter's address. - No MacVisor account. MacVisor made no account in an appliance, so
mvz shellandmvz execrefuse it, andmvz waitreturns once it runs (with--ssh, once port 22 answers on its first address). A FreeBSD-based appliance has no screen after FreeBSD's loader: use its web UI, or SSH if it runs sshd. - Shutting down. Shut Down, Restart,
mvz stopandmvz restartwork for every appliance. A Linux appliance gets the power button, then its agent or QEMU guest agent if it ignores the button. A FreeBSD-based one, such as a pfSense-based or OPNsense-based appliance, goes through MacVisor's agent if it's connected, then its QEMU guest agent if one answers on its second serial port (/dev/ttyV1.0), else gets the power button, pressed again a minute later. If it still runs after that, the Tasks pane says so: shut it down from its web UI or console, or use Power Off.
The VM's Overview shows an Appliance card with the appliance's addresses. Until an agent connects, the Overview's Guest Tools status and the VM window's guest agent item say Not Installed, with guest tools on or off, or Limited while a QEMU guest agent answers.
Made a VM from an appliance image with cloud-init on by mistake? Shut it down and turn cloud-init off: turn off Set up with cloud-init in VM Settings → Cloud-Init, or run mvz set <vm> --cloud-init off. It runs as an appliance from its next start. Its guest tools stay as they are, and a FreeBSD VM's agent keeps connecting: with Guest Tools on, it gets a small disc with only the agent's token at each start. Turning cloud-init back on brings back the setup it had.
Appliances in the catalogue
The Templates list's Appliances section, and mvz images, which labels them "(appliance)", offer these. A VM made from one is always an appliance: mvz create needs no --no-cloud-init for it and refuses --cloud-init, and New VM shows no cloud-init switch or account for it.
| Appliance | Id (aliases) | Source | Build |
|---|---|---|---|
haos-18 (haos, home-assistant) | github.com | Fixed build, 18.4. Its web page is at port 80 of its address | |
openwrt-25 (openwrt) | downloads.openwrt.org | Fixed build, 25.12.6. Its first network adapter is the LAN, the second the WAN; install qemu-ga in it (apk add qemu-ga) for Shut Down |
mvz create haos hass
mvz create openwrt openwrt-lab
macOS installers
The catalogue also holds Apple's macOS installers: macOS 27, the macOS 27.3 beta, 26, 15 and 14, and macos-latest for the newest this Mac supports. They're listed, with how MacVisor installs and sets up macOS, in macOS guests.
Distribution and Apple logos are trademarks of their respective owners.
How downloads are verified
The catalogue is signed and ships inside MacVisor. Every download uses HTTPS and is checked against the vendor's checksum, or for macOS against the SHA-256 of Apple's IPSW, before use. A local .ipsw you add is checked to be a restore image for virtual Macs. A download that fails a check is discarded.
Download, add and remove
mvz create ubuntu dev # downloads the image the first time, then makes the VM
mvz images pull debian-13 # download ahead of time
mvz images pull macos-26 # a macOS installer, for later VMs
mvz images add ~/Downloads/custom.qcow2
mvz images add ~/Downloads/UniversalMac_26.6.2_25G83_Restore.ipsw
mvz images rm "Fedora 43"
mvz images rm macos-26 # moves the IPSW to the Trash

- A Linux image becomes a template on first use, stored as ASIF in
<location>/Templates. VMs made from it are linked clones. createreuses the template you have.images pullfetches a newer build of a tracking entry, and existing VMs keep using the old one.images addturns a qcow2, raw,.xzor.gzfile into a template, or adds an.ipswto the installers. In the app, use the + in the Templates section.images pull <file|url> --os linux|freebsdsays which system a disk image is. Without it, MacVisor goes by the file's name, then its partitions. A pull that resumes after an interruption keeps its--os.images rmmoves a template or installer to the Trash. It refuses while VMs use the template, and asks first; in a script, add--yes.
Installers you download or add yourself stay until you remove them. One fetched only to create a VM goes to the Trash when a newer build of its release arrives, such as 27.0.2 for 27.0.1. A newer release, such as 27.2, doesn't replace it, so a 27.0.1 installer you have stays. New VM's Installer menu lists it by name, such as macOS 27.0.1 (26A434), and mvz create macos-27.0.1 <name> installs from it.
Where images are kept
| Path | Contents |
|---|---|
<location>/Templates/ | Cloud-image templates and your own templates |
<location>/Templates/Downloads/ | Downloads in progress, as <file>.partial |
<default location>/Templates/Installers/ | macOS installers. They live with your VMs, so uninstalling MacVisor keeps them. |
~/Library/Application Support/MacVisor/RuntimeCache | Container runtime files shared with new VMs |
Resuming and cancelling downloads
Cancel a download from the task pane or with mvz tasks cancel <task-id>. A cancelled or interrupted download keeps its partial file, and the next create or images pull of that image continues from there. One cut off by a service restart resumes by itself. Unused partial files are removed after two weeks.
If the server keeps refusing to resume a download, MacVisor starts it again from the beginning by itself, and the task says "The download kept failing; starting it again from the beginning". An image pieced together from several tries that fails its checksum is downloaded once more from the beginning before the pull gives up.
A VM made from an image that is still downloading, from the Templates list or for another VM, shows that download's progress in its row. Cancel on its row stops only that VM; the download goes on. See While a VM is being made.
MacVisor refuses a download that won't fit, and tells you how much space to free. If the disk fills up anyway, the download pauses until you make room and pull again.
What cloud-init sets up
On the first boot, a VM made from a cloud image gets:
| Item | Details |
|---|---|
| Your account | Your Mac user name and UID, so files in shared folders belong to you on both sides. The account has no password, unless the VM has Ubuntu Desktop or is a FreeBSD VM (for its console). |
| Your SSH keys | Every public key in ~/.ssh and your SSH agent. Choose keys with --ssh-key <file>. See SSH keys. |
| MacVisor Agent | Installed unless you pass --no-agent. |
| A container runtime | Only if you choose one: containerd with nerdctl, Docker, Podman, or k3s (pinned to v1.36.5+k3s1). |
| Shared folders | Only if you ask: --home shares your home folder read-only at the same path. |
| Ubuntu Desktop | Only if you choose it in the New VM form, for an Ubuntu image. See Ubuntu Desktop. |
| Rosetta | When it is installed on the Mac, so the guest can run x86-64 Linux programs. |
| Networking | DHCP on every adapter, the Default MacVisor Network unless --network says otherwise, and automatic port forwarding to the Mac (--no-forward turns it off). |
host.mvz.internal | Resolves to the Mac inside the guest: its address on the guest's network, on NAT, shared, host-only and bridged networks. Where the Mac has no address the guest can reach, it isn't set; it is never your router. host.macvisor.internal works too. See Names. |
| Your user data | From --user-data <file> or the form, applied after MacVisor's. |
A FreeBSD VM gets your account and SSH keys, a password for its console, sudo, ntpd and DHCP, and MacVisor installs its agent over SSH afterwards. It gets no container runtime, shared folders, Rosetta, automatic port forwarding or host.mvz.internal, and mvz wait returns when its first-boot setup has finished (MacVisor reads it over SSH). See FreeBSD guests.
mvz shell <vm> connects as soon as SSH answers. mvz wait <vm> returns when cloud-init has finished, including the runtime install. A disk grown with mvz set <vm> --disk <GiB> gets a bigger filesystem at the next boot.
Using the runtimes from the Mac. A Docker or Podman VM's API is forwarded to the Mac while it runs: use docker --context macvisor-<vm>. mvz create makes the context if docker is installed. Otherwise run mvz docker <vm>. For k3s, mvz kubeconfig <vm> --save writes a kubeconfig for 127.0.0.1:6443. Only one running k3s VM can use that port.
MacVisor caches nerdctl and k3s on the Mac after the first download, so later VMs don't fetch them from GitHub again.
First-boot progress
While a cloud-image VM's first boot runs, its subtitle in the VM list and the setup row on its Overview say what it's doing, such as Booting…, Installing guest tools, Installing Docker Engine, Setting up the desktop, Booting and updating FreeBSD or Installing MacVisor's agent over SSH, with the time left: "Installing guest tools · about 3 min left". The estimate comes from earlier setups of the same image on this Mac. Until there is one, it shows the time so far, and past the estimate it says "taking longer than usual". Package upgrades, the desktop install and FreeBSD's first boot say why they take a while. The Runner Log link under the step on the Overview shows every step with its time.
mvz show <vm> has the step as a Setup step row, and mvz wait <vm> prints each step as it comes.
Runtimes by distribution
Every runtime works on every catalogue image except those below. We tested each combination in October 2026. The New VM form hides runtimes an image can't run, and mvz create refuses them and lists the ones it offers. A template from the catalogue goes by its catalogue image, whatever you name it. For an image you added from a file or a URL, MacVisor goes by the file's name and the template's name, so an Ubuntu image saved as oracle-client.qcow2 is treated as Oracle Linux.
| Image | Not offered | Notes |
|---|---|---|
| Alpine Linux | Podman, k3s | containerd runs as a system service, so use sudo nerdctl. |
| Oracle Linux 9 | k3s | Docker Engine, Podman and containerd work. |
| Oracle Linux 10 | Docker Engine, k3s | Podman and containerd work. |
| Fedora, CentOS Stream | Nothing | The image already includes Podman, so it is there even with no runtime chosen. |
| FreeBSD | All four | Every runtime MacVisor installs is a Linux one. mvz create refuses --runtime. |
| Every other image | Nothing | All four runtimes. |
Oracle Linux VMs mount shared folders a few minutes after their first boot. The UEK kernel has no virtiofs until its modules package is installed. The agent fetches it in the background, which can take ten minutes on Oracle's mirrors, and mounts the shares once it's in. Rosetta doesn't run on UEK either, so boot the Red Hat compatible kernel for x86-64 programs. First boots take 5 to 10 minutes on Oracle's mirrors.
Give k3s VMs at least 4 GiB of memory, and keep the balloon target above half of it. A k3s guest squeezed further stops responding.
Signing in
| Guest | Account | Connect with |
|---|---|---|
| Linux from a cloud image | Your Mac user name, with your SSH keys. The account has no password, so the login prompt in the VM window can't be used. | Open in Terminal on the Overview, or mvz shell <vm> |
| Linux with Ubuntu Desktop | Your Mac user name, signed in to the desktop by itself, with your SSH keys. Its random password (mvz password <vm>) is for the lock screen and admin prompts. | The VM window, Open in Terminal, or mvz shell <vm> |
| FreeBSD | Your Mac user name, with your SSH keys. At the console it signs in with the password you chose, or a random one (mvz password <vm>); SSH takes keys only. | Open in Terminal on the Overview, mvz shell <vm>, ssh <vm>.mvz, or the console in the VM window |
For macOS guests, see Signing in on their own page.
After mvz ssh-config --install, ssh <vm>.mvz works too. See Names.
DeltaSync