How to Configure Custom Container Networks with Specific Subnets on macOS 26

Use the container network create command with --subnet and --subnet-v6 flags to define IPv4 and IPv6 CIDR blocks, which the runtime validates and binds to the macOS vmnet framework via the NetworkConfiguration object.

The apple/container repository provides a native container runtime for macOS that leverages the vmnet framework to create isolated virtual networks. When running containers on macOS 26 (Sequoia), you can define custom network subnets to segment traffic and avoid IP conflicts with existing networks. This article explains how the CLI translates your subnet parameters into vmnet configurations and how to manage these networks throughout their lifecycle.

How Container Networking Works on macOS

The container tool implements networking through the macOS vmnet framework, creating Layer 2 segments that operate independently of your host's physical interfaces. When you execute container network create, the CLI constructs a NetworkConfiguration object defined in Sources/ContainerResource/Network/NetworkConfiguration.swift. This structure captures your specified subnets in the ipv4Subnet and ipv6Subnet fields, then serializes them for the backend service.

The NetworksService actor (Sources/ContainerAPIService/Server/Networks/NetworksService.swift) handles the server-side validation. It checks that your CIDR blocks do not overlap with existing networks before instantiating either an AllocationOnlyVmnetNetwork or ReservedVmnetNetwork from the Sources/NetworkVmnet/Server/ directory. These implementations translate the configuration into actual vmnet allocations managed by the operating system.

Creating Networks with Custom Subnets

Specifying IPv4 and IPv6 CIDR Blocks

To create an isolated network with specific address ranges, use the --subnet and --subnet-v6 flags during network creation. The runtime accepts standard CIDR notation and validates the syntax before committing the configuration.

# Create a custom network with explicit IPv4 and IPv6 subnets

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

If you omit these flags, the runtime consults the user-wide configuration file at ~/.config/container/config.toml for default values.

Validating Network Configuration

After creation, verify that the network exists with your specified parameters:

container network list

The output displays the network name, state, and allocated subnets:

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

The NetworksService prevents overlapping subnets during creation. If you attempt to define a CIDR block that intersects with an existing network, the command fails before modifying the vmnet framework.

Configuring Default Subnet Ranges

If you regularly use specific subnet ranges, modify the defaults in ~/.config/container/config.toml to avoid repetitive flag usage:

[network]
subnet  = "192.168.100.0/24"
subnetv6 = "fd00:abcd::/64"

These values apply to any future container network create commands that omit the --subnet or --subnet-v6 flags. The configuration file is read during the initialization phase of the NetworksService before building the NetworkConfiguration object.

Attaching Containers to Custom Networks

Once a network exists, attach containers using the --network flag. The runtime assigns IP addresses from your defined CIDR blocks via the vmnet DHCP service.

# Run a container attached to the custom network

container run -d --name my-web-server \
    --network foo \
    --rm web-test

Verify the container received an address from the correct subnet:

container ls

The output shows the assigned IP within your custom range:

ID            IMAGE       OS   ARCH  STATE   IP
my-web-server web-test    linux arm64 running 192.168.100.2

Containers attached to the same network communicate directly at Layer 2, while remaining isolated from containers on other networks.

Managing and Removing Networks

Network deletion requires that no containers remain attached. Follow this workflow to clean up resources:

# Stop any running containers on the network

container stop my-web-server

# Remove the network definition

container network delete foo

The NetworksService checks for active allocations before removing the vmnet interface. If containers are still running, the command returns an error indicating dependencies exist.

Summary

• The container CLI uses the macOS vmnet framework through NetworkConfiguration objects defined in NetworkConfiguration.swift to manage subnets.
• Specify custom CIDR blocks with --subnet and --subnet-v6 flags during container network create.
• Default subnets can be configured permanently in ~/.config/container/config.toml.
• The NetworksService validates CIDR syntax and prevents overlapping networks before instantiating vmnet interfaces via AllocationOnlyVmnetNetwork or ReservedVmnetNetwork.
• Attach containers with --network <name> and remove networks only after stopping all dependent containers.

Frequently Asked Questions

Can I use any subnet range for container networks on macOS 26?

The container runtime validates that your CIDR blocks do not overlap with existing container networks or the host's network interfaces. According to the NetworksService.swift implementation, the system checks for conflicts before creating the vmnet interface. Private ranges such as 192.168.x.x/24 or IPv6 ULA addresses like fd00::/64 work correctly, provided they are not already allocated.

What happens if I don't specify subnet flags when creating a network?

When --subnet or --subnet-v6 are omitted, the runtime reads default values from ~/.config/container/config.toml. If no defaults exist in that file, the system uses built-in fallback ranges. The NetworkConfiguration initialization in NetworkConfiguration.swift handles this merge logic between CLI flags and configuration file values.

How do containers receive IP addresses from my custom subnet?

The vmnet framework provides DHCP services automatically. When you attach a container with --network, the AllocationOnlyVmnetNetwork or ReservedVmnetNetwork implementation requests an IP from the vmnet subsystem, which allocates an address from the CIDR range defined in your NetworkConfiguration. You can view the assigned address using container ls.

Why does network deletion fail with a dependency error?

The NetworksService maintains referential integrity between networks and running containers. If you attempt container network delete while containers are still attached, the service returns an error because the vmnet interface cannot be destroyed while in use. You must stop and remove all containers on the network before the deletion succeeds.

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