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

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, 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【/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 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)【/cache/repos/github.com/Lakr233/vphone-cli/main/sources/VPhoneCore/VPhoneBundleOps.swift#L87‑L101】.

To change the network configuration from the terminal:

# 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) 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 (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:

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) 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.
• 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, 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 (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】.

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