How to Create and Manage Custom Container Networks with Specific Subnets on macOS 26+

The container CLI uses the macOS vmnet framework to create isolated virtual networks, allowing you to specify custom IPv4 and IPv6 subnets via --subnet and --subnet-v6 flags during network creation, with configurations stored in NetworkConfiguration objects and managed by the NetworksService actor.

The apple/container project implements container networking on macOS 26+ using the native vmnet framework to provide isolated L2 segments. When you create and manage custom container networks with specific subnets, the system leverages NetworkConfiguration structs to validate CIDR blocks and the NetworksService actor to prevent conflicts before delegating to vmnet-based implementations like AllocationOnlyVmnetNetwork or ReservedVmnetNetwork.

Understanding the vmnet-Based Network Architecture

The networking layer relies on Apple's vmnet framework rather than traditional Linux bridge interfaces. When you execute container network create, the CLI instantiates a NetworkConfiguration object defined in Sources/ContainerResource/Network/NetworkConfiguration.swift. This struct captures your subnet preferences in the ipv4Subnet and ipv6Subnet fields, which hold CIDR strings such as 192.168.100.0/24 or fd00:1234::/64.

The NetworksService actor, located in Sources/ContainerAPIService/Server/Networks/NetworksService.swift, processes these configurations server-side. It validates CIDR notation, checks for overlaps with existing networks, and then hands the configuration to the vmnet implementation. The actual IP allocation is handled by AllocationOnlyVmnetNetwork or ReservedVmnetNetwork in Sources/NetworkVmnet/Server/AllocationOnlyVmnetNetwork.swift, which creates the isolated virtual interface based on your specified ranges.

Creating Custom Container Networks with Specific Subnets

Specifying IPv4 and IPv6 CIDR Blocks

To create a network with explicit addressing, use the --subnet flag for IPv4 and --subnet-v6 for IPv6. The CLI forwards these values to the NetworkConfiguration initializer, which stores them in the ipv4Subnet and ipv6Subnet properties.

# Create a custom network named "foo" with explicit subnets

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

Validation and Conflict Detection

During creation, the NetworksService validates that your CIDR strings are well-formed and ensures they do not overlap with existing networks. This check prevents routing conflicts between isolated container segments before the runtime commits the configuration to its filesystem store.

Configuring Default Network Subnets

If you frequently use specific subnet ranges, define defaults in ~/.config/container/config.toml rather than passing flags each time. These values apply automatically when container network create omits the --subnet or --subnet-v6 arguments.

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

Attaching Containers to Custom Networks

Once created, attach containers using the --network flag. The ContainerNetworkClient implementation automatically assigns IP addresses from your allocated subnet.

# Run a container attached to the custom network

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

Verify the IP assignment matches your custom subnet:

# See the container's IP address on the "foo" subnet

container ls
#> ID            IMAGE       OS   ARCH  STATE   IP
#> my-web-server web-test    linux arm64 running 192.168.100.2

Managing and Removing Networks

List existing networks to view their state and allocated subnets:

container network list
#> NETWORK  STATE    SUBNET
#> default  running  192.168.64.0/24
#> foo      running  192.168.100.0/24

Delete a network only after stopping all attached containers. The NetworksService prevents deletion while containers are still connected.

container stop my-web-server
container network delete foo

Summary

• The apple/container project uses the macOS vmnet framework via NetworkConfiguration objects to define isolated networks on macOS 26+.
• Specify custom subnets with --subnet and --subnet-v6 flags during container network create.
• The NetworksService actor validates CIDR blocks in Sources/ContainerAPIService/Server/Networks/NetworksService.swift and prevents overlapping network configurations.
• Define default subnets in ~/.config/container/config.toml to avoid repetitive CLI flags.
• Containers attach to custom networks via --network <name> and receive IPs from the allocated ranges via AllocationOnlyVmnetNetwork or ReservedVmnetNetwork.

Frequently Asked Questions

What is the vmnet framework and why does container use it?

The vmnet framework is Apple's native macOS API for creating virtual network interfaces and isolated L2 segments. According to the apple/container source code, the project uses vmnet-based implementations like AllocationOnlyVmnetNetwork defined in Sources/NetworkVmnet/Server/AllocationOnlyVmnetNetwork.swift to provide Docker-style networking without requiring Linux-specific kernel features, making it compatible with macOS 26+ virtualization.

How do I prevent subnet conflicts when creating custom networks?

The NetworksService actor in Sources/ContainerAPIService/Server/Networks/NetworksService.swift automatically validates new network configurations against existing ones. It checks that the ipv4Subnet and ipv6Subnet CIDR blocks from your NetworkConfiguration do not overlap with currently running networks, returning an error if a conflict is detected before the network is created.

Can I modify a network's subnet after creation?

No, you cannot modify the subnet configuration of an existing network. The ipv4Subnet and ipv6Subnet values are immutable properties of the NetworkConfiguration struct stored by the runtime's filesystem store. To change subnets, you must delete the existing network (after stopping all attached containers) and recreate it with the new CIDR values using container network create.

Where does container store network configuration on macOS?

Network configurations are stored in the runtime's filesystem store managed by the NetworksService actor. While the backend handles persistence automatically, user defaults for subnet ranges can be defined in ~/.config/container/config.toml, which the CLI reads before building NetworkConfiguration objects for new networks.

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