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

> Discover why hostOnly networking is unsupported in VPhoneNetworking. Learn about Virtualization.framework constraints and the specific error VPhoneNetworkingError.hostOnlyUnsupported.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: deep-dive
- Published: 2026-09-13

---

**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`](https://github.com/Lakr233/vphone-cli/blob/main/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:

```swift
// 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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneNetworking.swift)**: Implements validation, bridge-interface resolution, and concrete device creation. Throws `hostOnlyUnsupported` at lines 20-22.
- **[`VPhoneVirtualMachineManifest.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachineManifest.swift)**: Defines `NetworkConfig` with the `hostOnly` case and documents the default network mode.
- **[`NetworkingTests.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.