# How to Configure Network Settings for a Virtual iPhone in vphone-cli

> Learn how to configure network settings for a virtual iPhone in vphone-cli. Use the vphone vm config command to set NAT, bridged, or none network modes for your VM.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: how-to-guide
- Published: 2026-09-05

---

**Use the `vphone vm config` command to set the network mode to `nat`, `bridged`, or `none`, which updates the `NetworkConfig` struct in the VM's `config.plist` manifest and is applied via Virtualization.framework during the next boot.**

The `vphone-cli` tool by Lakr233 provides granular control over iOS virtual machine networking through a declarative manifest system. Understanding how to configure network settings for a virtual iPhone in `vphone-cli` requires familiarity with the `NetworkConfig` structure, the supported attachment modes, and the validation logic that translates manifest entries into `VZNetworkDeviceConfiguration` objects at runtime.

## Understanding the Network Configuration Architecture

### The NetworkConfig Struct

Network settings in `vphone-cli` are stored in the VM's **manifest** (`config.plist`). The core definitions reside in [`VPhoneVirtualMachineManifest.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachineManifest.swift), which declares a `NetworkConfig` struct containing three key fields:

- **`mode`**: An enumeration defining the attachment type (`nat`, `bridged`, or `off`)
- **`bridgeInterface`**: The host interface identifier (required when `mode` is `bridged`)
- **`macAddress`**: Reserved for future use (the framework currently assigns MAC addresses automatically)

The struct definition and its default values are located at lines 5–27 of [`VPhoneVirtualMachineManifest.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachineManifest.swift)【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/VPhoneCore/VPhoneVirtualMachineManifest.swift#L5‑L27】.

### Supported Network Modes

`vphone-cli` implements three distinct networking paradigms via Virtualization.framework:

- **NAT** (`nat`): Default mode using `VZNATNetworkDeviceAttachment`. The VM shares the host's IP address through network address translation.
- **Bridged** (`bridged`): Uses `VZBridgedNetworkDeviceAttachment` to bind the virtual NIC directly to a specified host network interface (e.g., `en0`).
- **Off** (`none`/`off`): No network device is attached to the VM, providing complete network isolation.

Host-only networking is explicitly unsupported. The source code in [`VPhoneNetworking.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneNetworking.swift) defines `VPhoneNetworkingError.hostOnlyUnsupported` at lines 6–9 to reject this mode during validation【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/VPhoneCore/VPhoneNetworking.swift#L6‑L9】.

## Configuring Network Settings via the CLI

The primary interface for modifying network settings is the `vphone vm config` command. This command invokes `VPhoneBundleOps.updateConfig`, which merges new values into the existing manifest via `VPhoneNetworking.merge` (lines 87–101 of [`VPhoneBundleOps.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneBundleOps.swift))【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/VPhoneCore/VPhoneBundleOps.swift#L87‑L101】.

To change the network configuration from the terminal:

```bash

# Enable NAT (default behavior)

vphone vm config MyVM --network nat

# Bridge to a specific host interface

vphone vm config MyVM --network bridged --bridge-interface en0

# Disable networking entirely

vphone vm config MyVM --network none

```

When `--bridge-interface` is omitted in bridged mode, `VPhoneNetworking.resolveBridgeInterface` (lines 48–67 of [`VPhoneNetworking.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneNetworking.swift)) automatically selects the first available bridgeable interface【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/VPhoneCore/VPhoneNetworking.swift#L48‑L67】.

## How Network Settings Are Applied at Runtime

### Validation and Merging

When you execute a configuration change, `VPhoneNetworking.merge` validates the input mode and resolves the bridge interface. The validation logic ensures:

1. The requested mode is supported (rejects `hostOnly`)
2. For bridged mode, a valid host interface is identified or provided
3. The resulting `NetworkConfig` is serializable back to the manifest

This process prevents invalid configurations from being persisted to `config.plist`.

### Device Construction During Boot

At VM startup, [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) (lines 188–191) reads the manifest's `networkConfig` and calls `VPhoneNetworking.makeNetworkDevice(_:)` to instantiate the appropriate `VZNetworkDeviceConfiguration`【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/vphone-cli/VPhoneVirtualMachine.swift#L188‑L191】【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/VPhoneCore/VPhoneNetworking.swift#L92‑L117】.

The factory method returns:
- A `VZNATNetworkDeviceAttachment` for NAT mode
- A `VZBridgedNetworkDeviceAttachment` bound to the resolved interface for bridged mode
- `nil` for off mode, resulting in an empty `networkDevices` array in the VM configuration

## Programmatic Configuration with Swift

For automation or custom tooling, you can manipulate network settings directly using the `VPhoneCore` framework:

```swift
import VPhoneCore

let lib = VPhoneLibrary.defaultRoot()
let bundle = try lib.bundle(named: "MyVM")
var manifest = bundle.manifest

// Configure bridged networking with a specific interface
let updatedNetwork = try VPhoneNetworking.merge(
    into: manifest.networkConfig,
    mode: .bridged,
    bridgeInterface: "en0"
)

// Persist the changes
manifest = manifest.updating(networkConfig: updatedNetwork)
try manifest.write(to: bundle.configURL)

```

This approach bypasses the CLI and directly invokes the same validation and persistence logic used by `vphone vm config`.

## Bridge Interface Requirements

Bridged networking requires specific entitlements to enumerate host interfaces. The helper function `VPhoneNetworking.availableBridgeInterfaces()` (lines 42–45 of [`VPhoneNetworking.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneNetworking.swift)) returns an empty array if the binary lacks the `com.apple.vm.networking` entitlement【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/VPhoneCore/VPhoneNetworking.swift#L42‑L45】.

Unsigned development builds must explicitly request this entitlement; otherwise, the bridged mode will fail with an error indicating no available interfaces.

## Summary

- **Manifest-driven configuration**: Network settings are stored in `config.plist` as a `NetworkConfig` struct defined in [`VPhoneVirtualMachineManifest.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachineManifest.swift).
- **Three supported modes**: NAT (default), bridged (requires host interface), and off (isolated).
- **CLI workflow**: Use `vphone vm config --network <mode>` to update settings; validation occurs in `VPhoneNetworking.merge`.
- **Runtime application**: `VPhoneNetworking.makeNetworkDevice(_:)` constructs the Virtualization-framework attachment during VM initialization.
- **Host-only unsupported**: The framework explicitly rejects `hostOnly` mode with `VPhoneNetworkingError.hostOnlyUnsupported`.
- **Bridged entitlement requirement**: The `com.apple.vm.networking` entitlement is required to list and use host bridge interfaces.

## Frequently Asked Questions

### Can I use host-only networking with vphone-cli?

No. According to the source code in [`VPhoneNetworking.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneNetworking.swift), host-only networking is explicitly unsupported because Apple’s Virtualization.framework does not provide a native attachment type for it. Attempting to configure this mode will result in a `VPhoneNetworkingError.hostOnlyUnsupported` error【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/VPhoneCore/VPhoneNetworking.swift#L6‑L9】.

### How do I change the network mode while the VM is running?

You must stop the VM before modifying network settings. The configuration is read once during the VM boot sequence in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) (lines 188–191) when `makeNetworkDevice` constructs the network attachment. Changes to `config.plist` made while the VM is running will only take effect on the next boot【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/vphone-cli/VPhoneVirtualMachine.swift#L188‑L191】.

### Why does bridged mode show no available interfaces?

The `VPhoneNetworking.availableBridgeInterfaces()` function returns an empty list if the `vphone-cli` binary lacks the `com.apple.vm.networking` entitlement. This is a common issue with unsigned local builds. You must codesign the binary with this entitlement to enumerate host network interfaces for bridging【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/VPhoneCore/VPhoneNetworking.swift#L42‑L45】.

### What happens if I specify an invalid bridge interface?

The `VPhoneNetworking.resolveBridgeInterface` method validates the provided interface identifier against the list of available bridgeable interfaces. If the specified interface is invalid or unavailable, the validation in `VPhoneNetworking.merge` will throw an error, and the manifest will not be updated, preventing the VM from failing to boot with a misconfigured NIC【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/VPhoneCore/VPhoneNetworking.swift#L48‑L67】.