# Understanding the vmnet Networking Architecture in Container: A Deep Dive > Explore Apple's container tool vmnet networking architecture. Learn how virtual networks are created and containers attach via isolated or non-isolated interfaces. - Repository: [Apple/container](https://github.com/apple/container) - Tags: deep-dive - Published: 2026-06-20 --- **Apple's container tool implements a three-tier vmnet networking architecture where container-apiserver coordinates an XPC helper (container-network-vmnet) that creates virtual networks using Apple's vmnet framework, while the runtime attaches container NICs to these networks via isolated or non-isolated interface strategies.** The vmnet networking architecture in container provides the foundation for network isolation and connectivity in Apple's open-source container runtime. By leveraging the hypervisor.framework's vmnet APIs, the tool creates virtual network interfaces that bridge containers to the host or external networks. This implementation spans multiple Swift source files across the `apple/container` repository, coordinating between a central API server, XPC networking services, and the Linux runtime. ## Core Components of the vmnet Architecture ### container-apiserver: The Central Coordinator The `container-apiserver` daemon acts as the orchestration layer that initializes the networking stack. When the system starts, it launches two critical XPC helpers: `container-core-images` for content management and `container-network-vmnet` for network provisioning. According to the technical documentation in [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md), this architecture ensures that network resource allocation runs in a separate privileged process from the main container lifecycle management. ### container-network-vmnet: The vmnet Interface The `container-network-vmnet` component, implemented in [`Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift), serves as the bridge between the container tool and Apple's vmnet framework. This XPC service creates virtual networks using native APIs such as `vmnet_network_create` and `vmnet_network_configuration_set_ipv4_subnet`. The core implementation resides in [`Sources/Services/NetworkVmnet/Server/ReservedVmnetNetwork.swift`](https://github.com/apple/container/blob/main/Sources/Services/NetworkVmnet/Server/ReservedVmnetNetwork.swift), which handles network serialization and maintains the `vmnet_network_ref` for container attachments. ### container-runtime-linux: Network Attachment Each container instance utilizes the `container-runtime-linux` service to connect to the vmnet infrastructure. The runtime selects between isolated and non-isolated interface strategies based on configuration. In `Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper+Start.swift`, the system maps the `container-network-vmnet` plugin name to the appropriate strategy, while [`Sources/Services/RuntimeLinux/Server/NonisolatedInterfaceStrategy.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/NonisolatedInterfaceStrategy.swift) implements the fallback logic using `vmnet_network_create_with_serialization` for default network scenarios. ## vmnet Network Modes and Isolation The vmnet framework supports two primary operational modes controlled through the [`ReservedVmnetNetwork.swift`](https://github.com/apple/container/blob/main/ReservedVmnetNetwork.swift) configuration layer: - **VMNET_HOST_MODE**: Creates a host-only network where containers can communicate with the macOS host but cannot access external networks. This mode sets `configuration.mode == .hostOnly` and blocks all traffic outside the host boundary. - **VMNET_SHARED_MODE**: Enables NAT-based connectivity allowing containers to reach external networks through the host's internet connection. This is the default mode when host-only isolation is not specified. macOS version capabilities vary significantly. On macOS 26 and later, vmnet supports fully isolated virtual networks where containers attached to the same network cannot communicate with each other. However, on macOS 15, the framework restricts users to a single default network, making container-to-container communication impossible and disabling the `--network` option entirely. ## Default Network Configuration and Subnet Management When initializing the networking stack via `container system start`, the XPC helper establishes a default vmnet network named **default** with the **CIDR 192.168.64.1/24**. This subnet is hardcoded across both the helper implementation and the vmnet framework itself. The gateway at `192.168.64.1` serves as the host endpoint, while containers receive IP addresses in the same range (e.g., `192.168.64.2/24`). Critical synchronization issues can arise if the helper and vmnet disagree on this subnet configuration, potentially resulting in completely isolated containers with no network connectivity. The serialization process in [`Sources/Services/NetworkVmnet/Server/ReservedVmnetNetwork.swift`](https://github.com/apple/container/blob/main/Sources/Services/NetworkVmnet/Server/ReservedVmnetNetwork.swift) ensures that the network reference persists correctly across container lifecycles. ## Lifecycle Flow: From System Start to Container Attachment The complete vmnet networking lifecycle follows this sequence: 1. **System Initialization**: Running `container system start` triggers `container-apiserver` to launch the `container-network-vmnet` XPC service. 2. **Network Creation**: The XPC helper creates a vmnet network in either host-only or shared mode using `vmnet_network_create`, configures IPv4/IPv6 subnets, and optionally disables DHCP. 3. **Container Request**: When executing `container run` or `container create`, the runtime requests network attachment from the XPC helper. 4. **Resource Allocation**: The helper returns a serialized `vmnet_network_ref` and assigns an IP address from the 192.168.64.0/24 range. 5. **Interface Attachment**: The runtime attaches the container's virtual NIC to the vmnet network, establishing the default gateway at `192.168.64.1`. 6. **Cleanup**: Upon container stop, the attachment releases, but the underlying vmnet network persists for the system service lifetime. ## Summary - The vmnet networking architecture in container consists of three layers: `container-apiserver` (orchestration), `container-network-vmnet` (XPC service wrapping vmnet APIs), and `container-runtime-linux` (interface attachment). - Network modes include `VMNET_HOST_MODE` (host-only) and `VMNET_SHARED_MODE` (NAT-enabled), configured in [`ReservedVmnetNetwork.swift`](https://github.com/apple/container/blob/main/ReservedVmnetNetwork.swift). - macOS 26+ supports isolated networks and multiple network instances, while macOS 15 restricts users to a single default network with no container-to-container communication. - The default subnet **192.168.64.1/24** requires synchronization between the helper and vmnet framework to prevent connectivity failures. - Key implementation files include [`NetworkVmnetHelper.swift`](https://github.com/apple/container/blob/main/NetworkVmnetHelper.swift), [`ReservedVmnetNetwork.swift`](https://github.com/apple/container/blob/main/ReservedVmnetNetwork.swift), and [`NonisolatedInterfaceStrategy.swift`](https://github.com/apple/container/blob/main/NonisolatedInterfaceStrategy.swift). ## Frequently Asked Questions ### What is the vmnet framework and how does container use it? The vmnet framework is Apple's API for creating virtual network interfaces on macOS. The container tool uses it through an XPC helper service (`container-network-vmnet`) that calls functions like `vmnet_network_create` to establish virtual networks and allocate IP addresses to containers. ### Why can't I use the --network option on macOS 15? macOS 15's implementation of the vmnet framework only supports a single default network instance. This limitation prevents the creation of multiple isolated networks and disables the `--network` flag, making container-to-container communication impossible on this version. ### How does container handle IP address assignment in vmnet networks? The `container-network-vmnet` XPC helper manages IP allocation from the predefined 192.168.64.1/24 subnet. When a container starts, the helper assigns an available IP address (e.g., 192.168.64.2) and returns it along with a serialized network reference to the runtime. ### What happens if the vmnet subnet configuration becomes desynchronized? If the XPC helper and vmnet framework disagree on the subnet configuration (particularly the 192.168.64.1/24 range), containers may receive IP addresses that don't match the actual network configuration, resulting in complete network isolation. This typically occurs during race conditions on first-container startup.