How Networking Is Handled in Apple's Container Runtime for VMs

Apple's container runtime leverages the macOS vmnet framework and an XPC helper service called container-network-vmnet to provide virtual network interfaces for Linux VMs, allocating IP addresses, MAC addresses, and routes through a pluggable architecture that supports isolated networks on macOS 26+.

Apple's container runtime runs each container inside its own lightweight Linux VM, with networking handled through a sophisticated integration with macOS virtualization frameworks. Understanding how networking is handled in Apple's container runtime for VMs requires examining the interplay between the vmnet framework, XPC services, and the pluggable network architecture implemented in the source code.

vmnet Framework Integration

The container CLI uses the Virtualization framework to launch VMs and the vmnet framework to create virtual network attachments. Each VM attaches to this virtual network, providing the container with network connectivity through a virtual NIC.

In Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift, the XPC helper implements the core logic for interfacing with vmnet. This helper runs as a separate XPC service, allowing the container runtime to request network allocations without blocking the main process.

XPC Network Helper Architecture

When container-apiserver starts, it launches the XPC service container-network-vmnet. This helper acts as a network control plane, allocating critical network resources for each container:

• IP addresses from the configured subnet
• MAC addresses for the virtual interface
• Gateway routes for external connectivity

The helper logs allocation events that reveal the network configuration process:

container-network-vmnet: allocated attachment [hostname=my-web-server.test.]
                                 [address=192.168.64.2/24] [gateway=192.168.64.1] [id=default]

This architecture separates privileged network operations from the main runtime, improving security and stability.

Network Plugin Model

The runtime implements a pluggable network model defined in Sources/ContainerResource/Network/NetworkConfiguration.swift. While container-network-vmnet serves as the default plugin, the architecture supports alternative networking implementations through the --plugin flag.

Key aspects of the plugin system include:

• Default plugin: container-network-vmnet provides vmnet-based networking out of the box
• Plugin selection: Users can specify custom plugins via CLI flags
• Configuration: Network settings are defined in ~/.config/container/config.toml, including default subnets

Interface Strategies and Network Isolation

Network interface creation follows specific strategies based on the macOS version and network type. In Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper+Start.swift, the runtime registers distinct interface strategies:

• IsolatedInterfaceStrategy: Used for standard VMs, providing full network isolation
• NonisolatedInterfaceStrategy: Available on macOS 26+ for reserved interfaces, allowing specific host-network integrations

Network capabilities vary significantly by macOS version:

1. macOS 15: The vmnet framework supports only a single default network; containers cannot communicate directly with each other over this network
2. macOS 26+: Users can create additional isolated networks using container network create, with each network isolated from others

Network Configuration and Runtime Flow

The networking stack follows a specific initialization sequence when starting containers:

1. container system start launches container-apiserver
2. container-apiserver spawns the container-network-vmnet XPC helper
3. Container creation triggers container-runtime-linux (the per-container helper)
4. The runtime helper contacts the XPC service to allocate network interfaces (IP, MAC, gateway)
5. The VM boots with the allocated interface; traffic traverses the vmnet virtual NIC to reach the host network or other isolated networks

Configuration options include:

• --network: Attach to a specific network (e.g., --network foo)
• --network with MAC/MTU: Specify custom MAC addresses or MTU sizes (e.g., --network foo,mac=02:42:ac:11:00:02)
• Default subnet: 192.168.64.1/24 (configurable in config.toml)

Practical Examples

Start the container system to initialize the network infrastructure:

# Start the container system (spawns the network XPC helper)

$ container system start

List and create networks:

# List available networks (shows "default" on macOS 15/26)

$ container network list
default

# Create a new isolated network (macOS 26+ only)

$ container network create foo --subnet 192.168.100.0/24

Run a container with custom network configuration:

# Run a container attached to the custom network with a specific MAC address

$ container run -d --name web \
    --network foo,mac=02:42:ac:11:00:02 \
    nginx:latest

Inspect the allocated network interface:

# Inspect the allocated network interface for the running container

$ container inspect web --format json | jq '.networks[0]'
{
  "network": "foo",
  "address": "192.168.100.2/24",
  "gateway": "192.168.100.1",
  "macAddress": "02:42:ac:11:00:02"
}

Summary

• vmnet integration: Apple's container runtime uses the macOS vmnet framework to create virtual network interfaces for Linux VMs, implemented in NetworkVmnetHelper.swift
• XPC architecture: The container-network-vmnet helper service handles IP, MAC, and route allocation separately from the main runtime
• Plugin model: Networking is pluggable via NetworkConfiguration.swift, with vmnet as the default and support for custom plugins via --plugin
• Interface strategies: RuntimeLinuxHelper+Start.swift implements IsolatedInterfaceStrategy for standard VMs and NonisolatedInterfaceStrategy for macOS 26+ reserved interfaces
• Version limitations: macOS 15 supports only a single default network with no container-to-container communication, while macOS 26+ enables multiple isolated networks via container network create
• Configuration: Default subnet is 192.168.64.1/24, customizable in ~/.config/container/config.toml

Frequently Asked Questions

What is the default network subnet in Apple's container runtime?

The default network subnet is 192.168.64.1/24. You can override this default in the user configuration file at ~/.config/container/config.toml, or specify custom subnets when creating isolated networks on macOS 26+ using container network create.

Why can't containers communicate with each other on macOS 15?

On macOS 15, the vmnet framework limitation restricts the runtime to a single default network that does not support container-to-container communication. Each container can reach the host and external networks, but direct inter-container traffic is blocked by the framework's architecture.

How do I create isolated networks for container groups?

On macOS 26+, use the container network create command to establish isolated networks. For example, container network create foo --subnet 192.168.100.0/24 creates a new network namespace. Containers attached to this network via --network foo are isolated from containers on other networks, though they share the same virtualized infrastructure.

What role does the XPC helper service play in container networking?

The container-network-vmnet XPC helper acts as a privileged network daemon. When container-apiserver starts, it launches this helper to allocate IP addresses, MAC addresses, and gateway routes for each container VM. This separation allows the unprivileged container runtime to request network resources without requiring direct access to the vmnet framework.

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