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

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, 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 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.

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

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

According to 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.

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

container network inspect dev-net

Expected output includes ipv4Subnet, ipv6Subnet, and gateway fields, confirming the network parameters stored in 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.

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

# 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, 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. 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.

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