MacVisor

Custom networks

Named shared and host-only networks: addressing on macOS 27, gateway services, DHCP reservations, network port forwards, and VLAN uplinks.

A custom network is a named private segment that any number of VMs can join. VMs on it reach each other directly. Its mode decides whether traffic can leave it. To build a lab with routers, firewalls and Kali, see a network and security lab on your Mac.

ModeWhat it connects
Shared (NAT)The VMs, plus an uplink that reaches the outside through the Mac
Host OnlyThe VMs and the Mac, nothing beyond

Manage networks in the Networks section of the sidebar or with mvz networks. VMs made from cloud images join the Default MacVisor Network.

A custom network: VM ports on one vmnet segment, gateway services, and an optional NAT uplink.

Defining a network

A network goes live when the first VM on it starts. Attach a VM in VM Settings → Network or with mvz set <vm> --network <network>. A running VM moves at its next start.

mvz networks                                   # list
mvz networks create lab                        # shared, automatic subnet
mvz networks create isolated --host-only       # host-only, automatic subnet
mvz set dev --network lab
mvz networks rm lab                            # refused while a VM uses it

If a VM won't start because MacVisor "couldn't provide the network", restart the background service (Restart in the dashboard's service section, or mvz service restart) and start the VM again. If it keeps happening, quit other virtualization apps that may hold the network's subnet.

After an update, the error can say instead that MacVisor's network process is from before the update. Then stop every VM that uses a custom network and start them again, which finishes the update. See After an update.

Addressing

Leave addressing empty and macOS picks a /24 inside 192.168.0.0/16. On macOS 27, macOS decides what you can pin, not MacVisor:

NetworkSubnetDHCPReservations
Shared (NAT)Chosen by macOS. A fixed subnet is refusedYesHonoured while the subnet stays the same
Host Only, automatic subnetChosen by macOSYesHonoured
Host Only, fixed subnetYours, a /24 inside 192.168.0.0/16NoneNot supported

Other settings:

  • DHCP off: macOS then keeps the Mac off the segment entirely, with no bridge and no gateway. Only the VMs see each other, and they need static addresses.
  • IPv6 prefix and length: a specific ULA prefix instead of a random one.
  • MTU: 1500 by default.

Keeping a subnet

MacVisor keeps each network on the same subnet, also while its VMs are stopped and from one login to the next.

Two things can still move a network to a new subnet: changing its settings, which recreates it, or another app (Docker Desktop, UTM, Internet Sharing) taking the subnet first, also while macOS has the network stopped (see below). Its VMs then get new addresses. mvz networks marks the subnet with * and says why it moved, and the Networks list says "changed from ...".

The firewall follows the new subnet. Reservations and addresses you wrote down elsewhere do not (see DHCP reservations for moving them). Reach VMs by name, which always follows the VM.

When macOS stops a network

macOS can stop a custom network under its VMs. It does this when a VM on Apple's NAT quits: one of yours on NAT, a macOS install, or another app's VM, such as one in UTM, Tart or Lima. The VMs on the network lose it until MacVisor makes the network again, within about a minute, and plugs them back in.

The network keeps its subnet unless something else took it in between. If it moves, the VMs get new addresses, so reach them by name. Each time, the Tasks pane shows Rebuilt network with the cause and whether the subnet stayed.

If macOS doesn't let MacVisor make the network again straight away, the Tasks pane shows Couldn't rebuild network, and the VMs on it stay without a network meanwhile. MacVisor tries again about two minutes later, then less often, at most every half hour, and plugs them back in once it has made the network. You don't need to restart them, unless the entry says MacVisor's network process is from before an update: then stop every VM that uses a custom network and start them again.

Services

Each network runs its own gateway services, and you can switch each one on or off.

ServicePurposeShared (NAT)Host Only
DHCP serverHands out addresses on the segmentConfigurableConfigurable, automatic subnet only
DNS proxyGuests resolve names through the MacConfigurableOff
IPv4 NAT (NAT44)Outbound IPv4 through the uplinkConfigurableOff
IPv6 NAT (NAT66)Outbound IPv6 through the uplinkConfigurableOff
Router advertisementIPv6 autoconfigurationConfigurableConfigurable

Services on a shared network: DHCP and reservations hand out addresses, DNS and IPv6 router advertisements configure guests, NAT44 and NAT66 provide the uplink, and port forwards publish selected services.

A host-only network has no uplink, so switching to Host Only turns the DNS proxy, NAT44 and NAT66 off.

On a shared network you can pin the uplink to one Mac interface. This helps on a Mac with both Wi-Fi and Ethernet, or to send traffic out through a VLAN interface.

While a network's firewall is on, NAT66 and router advertisement are off and greyed out. The firewall filters IPv4 only, and this stops guests from going around it over IPv6. Your settings return when you turn the firewall off. The exception is a shared network with NAT44 off: IPv6 NAT is its only way out, so its IPv6 stays on, unfiltered. Running VMs keep IPv6 until every VM on the network has stopped.

DHCP reservations

A reservation ties a MAC address to an address in the subnet. The guest keeps that address across reboots and reinstalls, with nothing to configure inside it. In the network's Reservations tab, the MAC picker lists the adapters of VMs already on the network.

mvz ip dev --wait                          # see which subnet the network has
mvz networks reserve lab dev 192.168.105.50

A reservation made by hand stays until you release it, also when its VM is deleted. Remove it in the Reservations tab, or run mvz networks release <network> <vm|ip>: by address is the way for one whose VM is gone. Like a new reservation, the change takes effect the next time the network is created.

Reservations have two requirements, both set by macOS:

  • The guest must send its MAC address in its DHCP request. Cloud-image Linux VMs do; FreeBSD VMs don't, so reach them as <vm>.mvz. A hand-installed Ubuntu sends a DUID until you set dhcp-identifier: mac in its netplan.
  • macOS must be serving DHCP, which it does on shared networks and on host-only networks with an automatic subnet.

A reservation takes effect the next time the network is created. That is the VM's next start if nothing else uses the network, otherwise once every VM on it has stopped. Until then the VM may run on a dynamic address, so use <vm>.mvz to reach it.

To put it in force without stopping the VMs, click Apply Now… in the network's editor, or run mvz networks apply <network>. MacVisor creates the network again, unplugging its running VMs for a few seconds. Their guests then ask for an address again and get the reserved one. Until then the reservation is marked waiting in the editor, in mvz networks and in mvz show, and the VM's Overview says so beside the address, with Show Network, which opens the network's editor. If another app takes the network's subnet during those seconds, the network moves to a new one, so guests with static addresses need new ones.

If the network moves to a new subnet, reservations left in the old one are flagged. Click Move to <subnet> in the Networks editor, or run mvz networks move-reservations <network>. Each reservation keeps its host number (.50 stays .50). Any whose new address is taken are skipped.

Automatic reservations

Every VM adapter that joins a custom network gets a reservation of its own, except a VM MacVisor didn't set up with cloud-init: an appliance, a Linux or FreeBSD VM installed from an ISO or imported. Their DHCP clients often don't identify by MAC address, so MacVisor shows the address they lease instead. One such VM keeps a reservation it already has. The VM's address is known before it boots and stays the same while it is on that network.

  • MacVisor assigns addresses from the top of the subnet down (.254, .253, ...), once the subnet is known, which is after a VM has run on the network. It keeps off addresses macOS has leased to any machine before: see When macOS gives a reserved address to another machine.
  • A reservation is released when the VM leaves the network or is deleted.
  • A reservation you make by hand for the same adapter replaces the automatic one.
  • The VM's Overview shows the reserved address until the guest reports one. mvz show <vm> lists it as Reserved IPv4, and mvz networks lists every reservation marked automatic or by hand.

A VM alone on its network

macOS forgets a network's reservations when the last adapter leaves it, and doesn't take them back when one plugs in again. An adapter leaves for a moment whenever its guest restarts or restarts the adapter, so MacVisor keeps a connection of its own on a network that has reservations while a VM is on it: a VM that is alone on its network keeps its reserved address through a restart from inside the guest. When the VM's cable itself comes out, MacVisor makes the network again, so the address is also kept after Disconnect and Connect, a move to another network and back, a start with its cable out, and the moment its cable is out after the Mac wakes. Plugging in takes a second or two longer for it.

When macOS gives a reserved address to another machine

macOS's DHCP server keeps a table of every address it has leased on each subnet, and never removes an entry. Once every address of a network's subnet has one, it reuses the oldest expired entry for the next new machine, without checking reservations. A reserved address that has such an entry, from whoever held it before the reservation was made, can then go to another VM while yours is using it: two machines on one address. It takes a few hundred VMs on one network over time, as a Mac that runs short-lived VMs for builds or tests has.

  • An address macOS never leased can't be given away, so MacVisor picks those for automatic reservations. A reservation it made earlier stays where it is.
  • mvz networks says where it can happen. at risk: lists reserved addresses that have an old lease in macOS's table. conflict: names an address that is on lease to another machine now.
  • mvz networks reserve says so when the address you chose has an old lease, and names one that has none.
  • mvz show <vm> says when that VM's reserved address is on lease to another machine as well.

To clear macOS's lease table:

  1. Shut down every VM, and quit other virtualization apps.
  2. Wait five minutes. macOS's DHCP server exits when idle, and keeps the table in memory until then.
  3. Run sudo rm /var/db/dhcpd_leases. macOS makes a new one.

VMs without a reservation may get another address afterwards. VMs with one keep theirs.

To turn automatic reservations off for a network, use the switch at the top of its Reservations tab or run mvz networks auto-addresses <network> off. This releases the reservations MacVisor made and keeps yours. Turning off DHCP Server, or giving a host-only network a fixed subnet, releases them too. The app asks first and says how many addresses go. Each VM that had one gets a new address when the network next starts, and turning the switch back on doesn't bring the same addresses back.

Network port forwarding

A network forward maps a TCP or UDP port on the Mac to an address and port on the segment, in the network's Port Forwarding tab. It needs no guest tools. Unlike a VM's own port forwards, which only this Mac can use, a network forward is reachable from other devices on the Mac's networks as well as from the Mac: use it to reach a VM from your LAN.

host :8443  ->  192.168.105.10:443
  • Forward to a VM. The button with the computer, beside the guest address, lists the VMs on the network. Picking one fills in its reserved address, and makes a reservation for it if it has none, so the forward keeps reaching the VM. You can still type an address, for a guest nested in a VM, say.
  • A VM's Overview lists the network forwards that reach it.
  • When it applies. macOS takes a network's forwards only when it makes the network, so a change is in force once no VM uses the network, or at once with Apply Now…, which the editor offers as soon as a forward changes while VMs use the network. Apply Now unplugs the network's running VMs for a few seconds.

Undoing a change

The network editor saves each change as you make it. Undo Last Change, in its footer, puts back the last change, on any tab: a firewall rule, a port forward or a reservation removed by a misclick comes back with its settings. Click it again to go further back, or press ⌘Z. A firewall change you undo is in force at once, like any change to the firewall; other changes apply when the network is made again, as above.

Seeing what is attached

The network's detail view lists every VM adapter configured for it:

  • Green: seen on the network.
  • Orange: the VM is running but nothing has been seen from that adapter, or it failed to attach. Check the VM's runner log.
  • Stopped: configured, not running.

A port group with eight attached VMs and its NAT gateway.

The Networks section also lists the Mac's own interfaces, including VLAN interfaces, with their addresses and attached VMs.

VLAN interfaces

Apple's Virtualization framework can't tag VLANs, so MacVisor creates 802.1Q VLAN interfaces on the Mac. Click New VLAN Interface… and give it a name, a tag from 1 to 4094, and a parent interface.

The result works in two ways: a VM adapter can bridge to it, and a shared network can use it as its uplink.

A physical Ethernet interface can carry multiple tagged host VLAN interfaces; MacVisor exposes each as a bridge target or custom-network uplink.

For an administrator account, the network helper creates and deletes VLAN interfaces without asking again. It deletes only interfaces MacVisor created. You are asked for an administrator password each time when:

  • you use a standard account, or the helper isn't installed, or
  • you delete a VLAN interface the helper didn't create (one made in System Settings, or by an earlier MacVisor).

Deleting a network

Deleting a network removes its definition. The app and mvz networks rm refuse while any VM uses it. That includes a suspended VM whose saved session was made on that network, even if you've since moved the VM elsewhere, because the session resumes on its original network. Resume that VM and shut it down, or start it from disk, first.

VMs that still point at a deleted network move to the Default MacVisor Network the next time they are cloned or imported. Point their adapters at another network first.