# Networking Capabilities of apple/container: Complete Guide to macOS Container Networking > Explore apple/container networking capabilities for macOS containers. Discover NAT, host-only modes, and a flexible plugin architecture for custom network drivers. - Repository: [Apple/container](https://github.com/apple/container) - Tags: deep-dive - Published: 2026-06-27 --- **The apple/container repository provides a complete, extensible networking stack for macOS containers featuring NAT and host-only modes, vmnet-based runtime implementation, XPC-based client communication, and a plugin-first architecture for custom network drivers.** The apple/container project delivers a sophisticated networking subsystem that defines the networking capabilities of apple/container for containerized workloads on macOS. This Swift-based implementation separates network definition from runtime execution, enabling developers to create isolated virtual networks using Apple's native vmnet framework. Understanding these networking capabilities is essential for anyone deploying containers on macOS with custom network configurations. ## Network Configuration and Resource Model Container networks in apple/container are defined by the `NetworkConfiguration` type, which provides a persistent, JSON-serializable description of network properties. Located in [`Sources/ContainerResource/Network/NetworkConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Network/NetworkConfiguration.swift), this structure captures the essential parameters required to instantiate a virtual network. Key configuration properties include: - **`name`** – A unique identifier that serves as both the display name and internal ID, validated via `NetworkResource.nameValid(name)`. - **`mode`** – Specifies the network topology as either `nat` (default) or `hostOnly`, defined in [`Sources/ContainerResource/Network/NetworkMode.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Network/NetworkMode.swift). - **`ipv4Subnet` / `ipv6Subnet`** – Optional CIDR prefixes; when omitted, the runtime automatically allocates subnets from the available pool. - **`plugin`** – Identifies the helper binary that implements the network (default: `container-network-vmnet`). - **`options`** – Plugin-specific key-value pairs, such as `variant=reserved` for the vmnet implementation. The configuration enforces naming constraints and integrates with the container persistence layer, storing network definitions as JSON for durability across system restarts. ## Runtime Implementation with vmnet The default runtime implementation, `ReservedVmnetNetwork`, bridges container networking to macOS's native vmnet framework. Found in [`Sources/Services/NetworkVmnet/Server/ReservedVmnetNetwork.swift`](https://github.com/apple/container/blob/main/Sources/Services/NetworkVmnet/Server/ReservedVmnetNetwork.swift), this class conforms to the `NetworkService` protocol defined in [`Sources/Services/Network/Server/NetworkService.swift`](https://github.com/apple/container/blob/main/Sources/Services/Network/Server/NetworkService.swift). During initialization, the runtime validates that the requested mode is either `nat` or `hostOnly`, rejecting unsupported configurations. It then utilizes vmnet reservation APIs (`vmnet_network_create`, `vmnet_network_configuration_set_*`) to establish the virtual network interface. The implementation serializes the `vmnet_network_ref` into XPC messages via `serialize_network_ref`, enabling secure handoff to client processes. The `NetworkService` protocol requires three core operations: - **`status()`** – Returns a `NetworkStatus` object containing the allocated subnet, gateway address, and optional IPv6 configuration. - **`allocate(hostname:macAddress:session:)`** – Creates a per-container attachment, assigning IP addresses and MAC addresses to individual containers. - **`lookup(hostname:)`** – Resolves hostnames to their corresponding network attachments for service discovery. After calling `start()`, the runtime exposes network metadata through `NetworkStatus`, allowing clients to determine gateway addresses and available address ranges. ## XPC-Based Client Communication Client applications interact with network services through `NetworkClient`, located in [`Sources/Services/Network/Client/NetworkClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/Network/Client/NetworkClient.swift). This client establishes communication with the runtime helper via XPC (Inter-Process Communication), constructing Mach service labels following the pattern `..`. The client API provides three primary operations: - **`status()`** – Queries the runtime for current network configuration and health. - **`allocate(hostname:macAddress:on:)`** – Requests network attachment for a specific container, using an existing `XPCClientSession` for efficient connection reuse. - **`lookup(hostname:)`** – Performs hostname resolution against the network's allocation table. All XPC messages route through the `NetworkRoutes` enum (e.g., `.status`, `.allocate`, `.lookup`) using key constants defined in `NetworkKeys`. The client decodes JSON responses into typed Swift structures (`Attachment`, `NetworkStatus`), providing type-safe access to network metadata. ## Command-Line Interface The `container network` command family provides user-facing access to the networking API, with implementations residing in `Sources/ContainerCommands/Network/`. These commands map directly to `NetworkClient` methods: - **`container network create `** – Constructs a `NetworkConfiguration` from flags (`--internal`, `--subnet`, `--option`, `--label`, `--plugin`) and invokes `NetworkClient.create`. - **`container network list`** – Enumerates all persistent networks via `NetworkClient.list`, with `--quiet` filtering to names only. - **`container network inspect `** – Retrieves both configuration and runtime status. - **`container network delete `** – Removes the network configuration and releases runtime resources. - **`container network prune`** – Identifies and deletes unused networks. ## Plugin Architecture and Extensibility The networking stack employs a plugin-first design that decouples the API from implementation details. The `plugin` field in `NetworkConfiguration` determines which helper binary the system launches, with each plugin exposing a Mach service named `com.apple.container.network..`. New networking backends can be added by: 1. Implementing the `NetworkService` protocol. 2. Registering the service under the standard Mach service label. 3. Configuring the container to use the custom plugin name. The client remains agnostic to implementation specifics, passing only the plugin name to locate the appropriate service. This architecture supports future networking technologies without modifying the core client code. ## Practical Examples ### Creating a NAT Network ```swift import ContainerResource import ContainerAPIClient let config = try NetworkConfiguration( name: "frontend-network", mode: .nat, ipv4Subnet: CIDRv4("10.0.0.0/24"), plugin: "container-network-vmnet", options: ["variant": "reserved"] ) let client = NetworkClient() let network = try await client.create(configuration: config) print("Created network:", network.id) ``` ### Allocating Container Addresses ```swift let netClient = NetworkClient(id: "frontend-network", plugin: "container-network-vmnet") let session = netClient.connect() let (attachment, extra) = try await netClient.allocate( hostname: "web-server", macAddress: MACAddress("02:42:ac:11:00:02"), on: session ) print("Allocated IP:", attachment.ipv4Address) ``` ### CLI Network Management ```bash # Create isolated host-only network container network create dev-net --internal # List all networks container network list # Inspect network details container network inspect dev-net # Remove unused networks container network prune ``` ## Summary - **apple/container** provides a layered networking stack for macOS containers with clear separation between configuration, runtime, and client layers. - **NetworkConfiguration** in [`Sources/ContainerResource/Network/NetworkConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Network/NetworkConfiguration.swift) defines persistent network properties including NAT and host-only modes. - **ReservedVmnetNetwork** implements the `NetworkService` protocol using macOS vmnet APIs for actual network creation and address allocation. - **NetworkClient** communicates via XPC to perform operations like `allocate(hostname:macAddress:session:)` and `lookup(hostname:)`. - The **plugin architecture** allows custom networking implementations by conforming to `NetworkService` and registering Mach services. - The **CLI** in `Sources/ContainerCommands/Network/` provides direct access to create, inspect, and manage container networks. ## Frequently Asked Questions ### What network modes does apple/container support? The repository supports two built-in modes defined in [`Sources/ContainerResource/Network/NetworkMode.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Network/NetworkMode.swift): **NAT** (default) and **host-only**. NAT mode provides outbound network access through macOS's Internet sharing, while host-only creates isolated networks visible only to the host and attached containers. ### How does container network allocation work? The `ReservedVmnetNetwork` runtime implements `allocate(hostname:macAddress:session:)` from the `NetworkService` protocol. When a container starts, the client sends an XPC request to the network helper, which assigns an IP address from the configured subnet and returns an `Attachment` object containing the IPv4 address, MAC address, and gateway information. ### Can I create custom network plugins for apple/container? Yes. The architecture is plugin-first: implement the `NetworkService` protocol in [`Sources/Services/Network/Server/NetworkService.swift`](https://github.com/apple/container/blob/main/Sources/Services/Network/Server/NetworkService.swift), register your service under the Mach service label `com.apple.container.network..`, and specify your plugin name in the `NetworkConfiguration` options. The `NetworkClient` automatically locates and communicates with your service via XPC without requiring changes to the core codebase. ### Where are network configurations stored? Network configurations are persisted as JSON in the container storage layer, managed through `NetworkConfiguration` in [`Sources/ContainerResource/Network/NetworkConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Network/NetworkConfiguration.swift). The system validates names using `NetworkResource.nameValid(name)` and maintains the configuration across system restarts, enabling networks to persist between container engine restarts.