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

> Discover how Apple's container runtime uses vmnet to manage VM networking on macOS. Learn about IP allocation, MAC addresses, and isolated networks.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: internals
- Published: 2026-07-01

---

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

```bash
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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/config.toml))

## Practical Examples

Start the container system to initialize the network infrastructure:

```bash

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

$ container system start

```

List and create networks:

```bash

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

```bash

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

```bash

# 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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.