Networking

vftool provides two modes of network connectivity for virtual machines, both implemented via the VZVirtioNetworkDeviceConfiguration.

NAT Mode (Default)

By default, vftool configures a Network Address Translation (NAT) network for the VM using VZNATNetworkDeviceAttachment. This is the easiest way to provide network access and requires no special configuration.

When a VM is started with NAT mode, Virtualization.framework creates a virtual network that is firewalled from the host's external network. The host machine acts as a router for the guest.

  • Connectivity: The guest can make outgoing connections to the internet.
  • Host Access: The host machine can connect to services running inside the guest.
  • Host Interface: The framework typically creates a new network interface on the host (e.g., bridge100) with an IP like 192.168.64.1. The guest then receives an IP address in the same subnet (e.g., 192.168.64.2) via DHCP.
  • External Access: External machines on your local network cannot directly access services in the guest.

This mode is ideal for most development and testing use cases.

Bridged Mode

Bridged mode, configured with the -b <interface> flag, connects the VM's virtual network adapter directly to one of the host's physical network interfaces (e.g., en0 for Wi-Fi or Ethernet). This is implemented with VZBridgedNetworkDeviceAttachment.

In this configuration, the VM appears as a separate, independent device on your local network. It will typically receive its own IP address from your network's DHCP server.

The Bridged Networking Entitlement Issue

This mode is not expected to work for most users.

To use bridged networking, the application requires a special, restricted network entitlement from Apple: com.apple.vm.networking.

As noted in Apple's documentation:

This entitlement is restricted to developers of virtualization software. To request this entitlement, contact your Apple representative.

Without this entitlement, attempting to start a VM in bridged mode will fail. Since vftool cannot be distributed with this entitlement, NAT mode is the only functional option for general use.