# How to Create and Manage Custom Container Networks on macOS 26

> Learn to create and manage custom container networks on macOS 26 using the container network CLI or Swift API. Explore isolated virtual LANs powered by container-network-vmnet.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-11

---

**Custom container networks on macOS 26 are fully isolated virtual LANs powered by the `container-network-vmnet` plugin, created via the `container network` CLI or the `NetworkClient` Swift API, and managed through XPC communication with the Container API Server.**

The **apple/container** repository implements a native container networking stack for macOS 26 that abstracts the underlying `vmnet` framework into manageable virtual interfaces. When you create and manage custom container networks on macOS 26, you define isolated subnets that prevent traffic leakage between unrelated workloads, going beyond the built-in **default** network that starts automatically with the system.

## Understanding the Network Architecture

The container networking subsystem follows a layered design that separates user-facing tools from kernel-level vmnet interfaces.

### The vmnet Plugin and Default Network

At the core resides the **container-network-vmnet** plugin, which translates high-level network requests into native vmnet interfaces. When you run `container system start`, the platform initializes a built-in network called **default** (see [`Sources/Services/ContainerAPIService/Client/NetworkClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/NetworkClient.swift) lines 43-45). This network provides immediate connectivity for containers, but lacks the isolation required for multi-tenant or security-sensitive deployments.

Custom networks operate as completely isolated virtual LANs. Each custom network receives its own vmnet interface and cannot observe traffic from other networks, including the **default** network, as documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md).

### XPC Communication Flow

Every network operation traverses a secure XPC pipeline:

1. **CLI** parses arguments and builds an XPC message to the `com.apple.container.apiserver` Mach service
2. **Container API Server** receives the request and routes it to the network plugin
3. **Network Plugin** (`container-network-vmnet`) creates the vmnet interface, assigns IPv4/IPv6 CIDR blocks, and registers the state

The client-side implementation lives in [`NetworkClient.swift`](https://github.com/apple/container/blob/main/NetworkClient.swift) (lines 24-33), which handles the encoding of `NetworkConfiguration` objects and decoding of `NetworkResource` responses.

## Creating Custom Container Networks

You can provision isolated networks through the command line or programmatically via Swift.

### CLI Method with Custom Subnets

Use `container network create` to define a network with specific CIDR blocks. The following example creates a network named `foo` with explicit IPv4 and IPv6 ranges:

```bash

# Create a network with custom subnets

container network create foo \
    --subnet 192.168.100.0/24 \
    --subnet-v6 fd00:1234::/64

```

This command constructs an XPC `networkCreate` request (route: `.networkCreate`) and passes the encoded `NetworkConfiguration` to the server, ultimately invoking the `NetworkClient.create` method (see [`NetworkClient.swift`](https://github.com/apple/container/blob/main/NetworkClient.swift) lines 67-84).

### Swift API Implementation

For programmatic control, import the `ContainerResource` and `ContainerPlugin` modules and instantiate `NetworkClient`:

```swift
import ContainerResource
import ContainerPlugin

let client = NetworkClient()

// Define a custom network configuration
let config = NetworkConfiguration(
    id: "my-custom-net",
    name: "my-custom-net",
    subnet: "192.168.200.0/24",
    subnetv6: "fd00:abcd::/64",
    internal: false,
    labels: [:],
    options: [:],
    plugin: "container-network-vmnet"
)

// Create the network
let network = try await client.create(configuration: config)
print("Created network \(network.id) with IPv4 \(network.subnet)")

```

## Listing and Inspecting Networks

To view all provisioned networks, including their state and subnet assignments:

```bash
container network list

```

This executes the `NetworkClient.list` method (lines 91-104 in [`NetworkClient.swift`](https://github.com/apple/container/blob/main/NetworkClient.swift)), which sends a `networkList` XPC request and decodes the returned `[NetworkResource]`. The output resembles:

```text
NETWORK  STATE    SUBNET
default  running  192.168.64.0/24
foo      running  192.168.100.0/24

```

## Attaching Containers to Custom Networks

Launch containers on your isolated network using the `--network` flag:

```bash
container run -d --name web --network foo --rm web-test

```

Containers attached to `foo` can communicate with each other within the `192.168.100.0/24` range, but remain isolated from containers on the **default** network or other custom networks.

## Deleting and Pruning Networks

Networks persist until explicitly removed or pruned, provided no containers remain attached.

### Delete a Specific Network

Remove a network by name:

```bash
container stop web
container network delete foo

```

This triggers `NetworkClient.delete` (lines 21-33 in [`NetworkClient.swift`](https://github.com/apple/container/blob/main/NetworkClient.swift)), which sends a `networkDelete` request. The server verifies zero container attachments before destroying the vmnet interface.

### Prune Unused Networks

Clean up all unused networks while preserving the built-in **default** network:

```bash
container network prune

```

This command removes any network with zero container attachments, as documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md).

## Summary

- **Custom networks** on macOS 26 are isolated virtual LANs backed by the `container-network-vmnet` plugin, distinct from the built-in **default** network.
- **Creation** occurs via `container network create` or the `NetworkClient.create` API, supporting custom IPv4/IPv6 CIDR blocks.
- **Communication** flows through XPC to the `com.apple.container.apiserver` Mach service, implemented in [`Sources/Services/ContainerAPIService/Client/NetworkClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/NetworkClient.swift).
- **Lifecycle management** includes listing (`network list`), deleting (`network delete`), and pruning (`network prune`) operations that check for active container attachments.
- **Isolation** guarantees that traffic on one custom network cannot reach containers on another network or the default network.

## Frequently Asked Questions

### How does the default network differ from custom container networks on macOS 26?

The **default** network initializes automatically when you run `container system start` and provides general connectivity without custom CIDR configuration. **Custom networks** are explicitly created via `container network create` or the `NetworkClient` API, offering complete isolation from other networks and support for user-defined IPv4/IPv6 subnets. According to the apple/container source code, custom networks receive dedicated vmnet interfaces that filter traffic at the virtualization layer.

### Can I create internal networks that block external traffic?

Yes. When creating a network via the Swift API, set the `internal` parameter to `true` in the `NetworkConfiguration` initializer. This restricts the network to container-to-container communication only, preventing external routing. The CLI equivalent uses the `--internal` flag during `container network create`.

### What happens if I try to delete a network with running containers?

The deletion operation fails. The `NetworkClient.delete` method (implemented in [`NetworkClient.swift`](https://github.com/apple/container/blob/main/NetworkClient.swift)) sends a `networkDelete` request that triggers a server-side validation check. The server ensures no containers remain attached to the network before removing the vmnet interface. You must stop and remove all attached containers before the network can be deleted, or use `container network prune` to remove only unused networks.

### Where are network configurations stored in the apple/container repository?

Network configuration logic resides in [`Sources/Services/ContainerAPIService/Client/NetworkClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/NetworkClient.swift), which defines the XPC client methods for `create`, `list`, and `delete` operations. User-facing documentation appears in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (covering isolation and creation workflows) and [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (detailing CLI options). The plugin loader that registers `container-network-vmnet` is implemented in [`Sources/ContainerPlugin/PluginLoader.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginLoader.swift).