# How to Create and Manage Custom Container Networks with Specific Subnets on macOS 26+ > Learn to create and manage custom container networks with specific subnets on macOS 26+ using the container CLI and vmnet framework. Control IPv4 and IPv6 subnets easily. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-13 --- **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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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. ```bash # 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. ```toml [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. ```bash # 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: ```bash # 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: ```bash 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. ```bash 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`](https://github.com/apple/container/blob/main/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 ` 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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.