# How to Create and Manage Container Virtual Networks with Custom Subnets in Apple Container

> Learn to create and manage container virtual networks with custom subnets using Apple Container and the vmnet framework. Segment container traffic easily with the CLI.

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

---

**Apple Container uses the macOS vmnet framework to create isolated virtual networks with custom IPv4/IPv6 subnets, allowing you to segment container traffic by attaching containers to specific networks via the CLI.**

The `apple/container` repository provides a container runtime for macOS that leverages the **vmnet** framework for virtual networking. Understanding how to create and manage container virtual networks with custom subnets enables you to isolate workloads and control IP addressing schemes. This guide covers the architecture, CLI workflows, and configuration files based on the latest source code.

## Understanding the vmnet Architecture

Apple Container implements networking through the macOS **vmnet** framework. When you execute `container system start`, a helper process called **container-network-vmnet** bootstrap a default vmnet network named `default` and exposes an XPC API for IP address allocation.

### Network Isolation Model

Each virtual network lives in its own vmnet instance, providing complete Layer 2 isolation. Containers attached to different networks cannot communicate with each other directly. The system automatically creates only the `default` network; any user-defined network remains isolated from the default and from all other user-defined networks. As documented in [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md), this isolation ensures that multi-tenant or segmented workloads remain segregated at the network level.

### macOS Version Constraints

Network functionality varies by macOS version. On **macOS 15**, the vmnet framework cannot instantiate multiple isolated networks—only the default network exists, and the `container network` subcommands are unavailable. Starting with **macOS 26**, the full multi-network feature set is enabled, allowing creation of custom networks alongside the default. Check [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md) for specific version compatibility notes.

## Creating Networks with Custom Subnets

You define custom subnets during network creation using explicit flags or default configuration values. The CLI validates that requested subnets do not overlap with existing networks to prevent routing conflicts.

### Specifying Subnets via CLI Flags

Use the `--subnet` flag for IPv4 CIDR notation and `--subnet-v6` for IPv6 prefixes when running `container network create`. If omitted, the system allocates from default ranges.

```bash

# Create an isolated network with explicit IPv4 and IPv6 subnets

container network create prod-network \
    --subnet 10.0.100.0/24 \
    --subnet-v6 fd00:dead:beef::/64

```

The command registers the network with the `container-network-vmnet` process, which configures the vmnet interface accordingly. You can verify the allocation using `container network inspect`.

### Configuring Default Subnet Ranges

Default subnets for networks created without explicit flags are defined in `~/.config/container/config.toml`. Edit the `[network]` section to specify the CIDR ranges the system should allocate from next.

```toml
[network]
ipv4_subnet = "192.168.0.0/16"
ipv6_subnet = "fd00:container::/48"

```

According to [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md), these values determine the pool for dynamically assigned subnets when you omit the `--subnet` flags.

## Managing the Network Lifecycle

The `container network` command group provides full lifecycle management. All operations except `create` and `prune` require the target network to exist in the vmnet registry.

### Creating and Listing Networks

Create isolated networks using explicit or default subnets, then enumerate existing networks.

```bash

# Create a development network

container network create dev-net --subnet 172.20.0.0/16

# List all user-defined networks (excludes the default network)

container network list

```

The `list` subcommand queries the network database maintained by the `container-network-vmnet` helper.

### Inspecting Network Configuration

Retrieve detailed configuration including assigned subnets, gateway addresses, and driver information.

```bash
container network inspect dev-net

```

Expected output includes `ipv4Subnet`, `ipv6Subnet`, and `gateway` fields, confirming the network parameters stored in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) examples.

### Attaching Containers to Networks

When launching containers, specify the network name using the `--network` flag. You can optionally set a static MAC address or MTU using comma-separated key-value pairs.

```bash

# Run nginx on the custom network with static MAC

container run -d --name web \
    --network prod-network,mac=02:42:ac:11:00:02,mtu=1500 \
    nginx:latest

# Verify the MAC address inside the container

container exec web -- cat /sys/class/net/eth0/address

```

The vmnet framework assigns the container an IP address from the network's subnet range while respecting the provided MAC address override.

### Deleting and Pruning Networks

Remove unused networks to free vmnet resources. The `delete` command requires the network to have no attached containers.

```bash

# Remove a specific empty network

container network delete dev-net

# Remove all unused user-defined networks (preserves default)

container network prune

```

As noted in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), the `prune` operation targets only user-defined networks, ensuring the system `default` network remains intact.

## Summary

- **Apple Container** leverages the macOS vmnet framework via the `container-network-vmnet` helper to provide isolated virtual networks.
- Each network operates in its own vmnet instance, preventing cross-network communication between containers on different subnets.
- Use `container network create --subnet <cidr>` to define custom IPv4 ranges and `--subnet-v6` for IPv6 prefixes.
- Default subnet pools are configurable in `~/.config/container/config.toml` under the `[network]` section.
- Multi-network support requires **macOS 26**; **macOS 15** supports only the default network.
- Attach containers to specific networks using `--network <name>` with optional `mac=` and `mtu=` parameters.

## Frequently Asked Questions

### Can containers communicate across different custom networks?

No. Each network exists in an isolated vmnet instance. Containers attached to different networks cannot communicate directly with each other, as documented in [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md). Traffic isolation is enforced at the hypervisor level by the vmnet framework.

### Where does Apple Container store the default subnet configuration?

Default subnets are stored in the user-level configuration file at `~/.config/container/config.toml` within the `[network]` table. You can modify `ipv4_subnet` and `ipv6_subnet` values to change the allocation pools used when creating networks without explicit `--subnet` flags.

### Why are network commands unavailable on macOS 15?

The vmnet framework in macOS 15 lacks support for multiple isolated network interfaces. Consequently, the `container network` subcommands are disabled on macOS 15, and only the default network exists. Upgrade to macOS 26 to access the full multi-network functionality and custom subnet features.

### How do I assign a static IP address to a container?

Apple Container does not support static IP assignment via CLI flags. Instead, the vmnet framework dynamically assigns IP addresses from the network's subnet range. You can, however, specify a static **MAC address** using `--network <name>,mac=<address>`, which allows DHCP reservations or deterministic IP allocation based on MAC.