Why hostOnly Networking Is Unsupported in VPhoneNetworking: Virtualization.framework Constraints Explained

VPhoneNetworking explicitly rejects host-only networking because Apple's Virtualization.framework provides no native VZHostOnlyNetworkDeviceAttachment, forcing the library to throw VPhoneNetworkingError.hostOnlyUnsupported when this mode is requested.

The Lakr233/vphone-cli project implements virtualization through Apple's native frameworks, but its networking layer cannot accommodate host-only configurations. This limitation stems directly from the underlying Virtualization.framework API surface, which constrains how virtual network interfaces attach to guest systems.

The Root Cause: Missing Virtualization.framework Attachment

Apple's framework exposes only three concrete network device attachments. According to the source code in VPhoneNetworking.swift, the available options are:

• VZNATNetworkDeviceAttachment for NAT mode
• VZBridgedNetworkDeviceAttachment for bridged mode
• nil for disabled networking

There is no VZHostOnlyNetworkDeviceAttachment class available. Consequently, when the manifest requests hostOnly, the code at lines 20-22 throws VPhoneNetworkingError.hostOnlyUnsupported. The inline comment explicitly states: "hostOnly has no native Virtualization.framework attachment."

In the makeNetworkDevice function (lines 96-101), a switch-case handles the configuration, but the hostOnly case lacks a corresponding attachment implementation. Attempting to boot with this configuration would either crash or produce silent failures, so the library proactively validates and rejects it.

Entitlement Restrictions for Unsigned Binaries

Even if the attachment existed, host-only networking requires the com.apple.vm.networking entitlement. This entitlement is unavailable to unsigned test binaries, creating additional barriers for development environments using vphone-cli.

Supported Networking Configurations

Since host-only is unavailable, VPhoneNetworking provides three validated alternatives:

NAT Mode (Default)

Routes guest traffic through the host using VZNATNetworkDeviceAttachment. This is the default configuration when no specific interface is required.

Bridged Mode

Attaches the guest directly to a physical network interface selected from VZBridgedNetworkInterface.networkInterfaces. Use resolveBridgeInterface(requested:current:) to select the appropriate interface.

Off Mode

Explicitly disables networking by passing nil as the attachment, resulting in no NIC being attached to the virtual machine.

Code Examples: Valid vs. Invalid Configurations

The following Swift examples demonstrate how to instantiate each supported network device using VPhoneNetworking.makeNetworkDevice(_:), plus the failing host-only attempt:

// 1️⃣ NAT (default)
let natConfig = try VPhoneNetworking.makeNetworkDevice(.init(mode: .nat,
                                                            macAddress: "",
                                                            bridgeInterface: nil))

// 2️⃣ Bridged – pick a host interface first
let bridgeIf = try VPhoneNetworking.resolveBridgeInterface(requested: nil,
                                                          current: nil)
let bridgedConfig = try VPhoneNetworking.makeNetworkDevice(.init(mode: .bridged,
                                                                 macAddress: "",
                                                                 bridgeInterface: bridgeIf))

// 3️⃣ No network device (off)
let offConfig = try VPhoneNetworking.makeNetworkDevice(.init(mode: .off,
                                                            macAddress: "",
                                                            bridgeInterface: nil))

// 4️⃣ Host‑Only – throws VPhoneNetworkingError.hostOnlyUnsupported
// let hostOnlyConfig = try VPhoneNetworking.makeNetworkDevice(.init(mode: .hostOnly,
//                                                                macAddress: "",
//                                                                bridgeInterface: nil))

Key Source Files

Understanding this limitation requires examining specific files in the Lakr233/vphone-cli repository:

• VPhoneNetworking.swift: Implements validation, bridge-interface resolution, and concrete device creation. Throws hostOnlyUnsupported at lines 20-22.
• VPhoneVirtualMachineManifest.swift: Defines NetworkConfig with the hostOnly case and documents the default network mode.
• NetworkingTests.swift: Unit tests confirming that requesting hostOnly triggers the expected error.

Summary

• VPhoneNetworking disables host-only networking by design due to missing Virtualization.framework support.
• The error VPhoneNetworkingError.hostOnlyUnsupported is thrown proactively in VPhoneNetworking.swift to prevent boot failures.
• Apple's framework provides only NAT, Bridged, and Off attachment types; no VZHostOnlyNetworkDeviceAttachment exists.
• The com.apple.vm.networking entitlement requirement makes host-only networking impossible for unsigned binaries anyway.
• Use NAT for isolated guest internet access, Bridged for direct network integration, or Off to disable networking entirely.

Frequently Asked Questions

What error does VPhoneNetworking throw when requesting host-only mode?

The library throws VPhoneNetworkingError.hostOnlyUnsupported, defined in VPhoneNetworking.swift at lines 20-22. This error prevents the virtual machine from attempting to boot with an unsupported network configuration.

Does Virtualization.framework support host-only networking?

No. Apple's Virtualization.framework only supplies VZNATNetworkDeviceAttachment, VZBridgedNetworkDeviceAttachment, and nil for network device attachments. There is no VZHostOnlyNetworkDeviceAttachment class available in the current API.

Can I work around the host-only limitation in VPhone?

No workaround exists within the current implementation. The makeNetworkDevice function in VPhoneNetworking.swift explicitly handles the hostOnly case by throwing an error, and the underlying framework lacks the necessary attachment type to support it. You must use NAT, Bridged, or Off modes instead.

Which networking mode should I use instead of host-only?

For guest isolation with internet access, use NAT mode (the default). For direct LAN access where the guest appears as a physical device, use Bridged mode with a specific interface from VZBridgedNetworkInterface.networkInterfaces. Use Off mode only when the guest requires no network connectivity.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}