How to Create a Container Network with a Custom Subnet in Apple Container

Create a network with a custom subnet by passing the --subnet and --subnet-v6 flags to container network create, or configure default subnets permanently in ~/.config/container/config.toml under the [network] section.

The Apple Container runtime leverages macOS's vmnet framework to provide network isolation for containers. While the system automatically assigns non-overlapping CIDR blocks when you create networks, you can define custom IPv4 and IPv6 subnets to ensure deterministic container addressing that aligns with your infrastructure requirements.

Setting a Custom Subnet During Network Creation

You can specify exact CIDR ranges when creating individual networks using command-line flags. According to the documentation in docs/how-to.md (lines 317-322), the --subnet flag accepts an IPv4 CIDR block, while --subnet-v6 accepts an IPv6 CIDR block.

Create a network named frontend with specific IPv4 and IPv6 ranges:

container network create frontend \
    --subnet 192.168.200.0/24 \
    --subnet-v6 fd00:dead:beef::/64

As documented in docs/command-reference.md (lines 777-791), these flags map directly to the network configuration stored by the runtime. After creation, containers attached to this network will receive IP addresses from the specified 192.168.200.0/24 and fd00:dead:beef::/64 pools.

Configuring Default Subnets Globally

To avoid specifying subnets for every new network, configure default values in TOML configuration files. This applies to all networks created without explicit --subnet flags.

User-Level Configuration

Create or edit ~/.config/container/config.toml to set personal defaults:

[network]

# Default IPv4 subnet for networks created without --subnet

subnet = "192.168.100.0/24"

# Default IPv6 subnet for networks created without --subnet-v6

subnetv6 = "fd00:abcd::/64"

As noted in docs/how-to.md (lines 358-365), these values apply to all networks created by the current user when explicit flags are omitted.

System-Wide Configuration

For multi-user environments, place the same [network] configuration in /etc/container/config.toml. This system-level file uses identical TOML keys and applies to all users on the machine, as detailed in docs/container-system-config.md (lines 19-70).

Validation and Conflict Prevention

The runtime implements overlap detection to prevent IP conflicts. When you specify a custom subnet, the system validates that the CIDR block does not intersect with any existing container network. If a conflict is detected, the container network create command aborts with an error specifying the overlapping range. This safeguard ensures network isolation is maintained unless explicitly routed otherwise.

Verifying Network Configuration

After creating a network, inspect its assigned subnets using the list command:

container ls --network frontend

The output displays the network name and the specific CIDR blocks that attached containers will receive, confirming whether your custom subnets or the defaults were applied.

Summary

• Use container network create <name> --subnet <CIDR> --subnet-v6 <CIDR> for per-network custom subnets
• Configure persistent defaults in ~/.config/container/config.toml or /etc/container/config.toml under the [network] section using the subnet and subnetv6 keys
• The runtime validates custom subnets against existing networks to prevent overlap
• Verify assigned subnets with container ls --network <name>

Frequently Asked Questions

Can I specify both IPv4 and IPv6 subnets simultaneously?

Yes. The container network create command accepts both --subnet for IPv4 and --subnet-v6 for IPv6 in a single invocation. For example: --subnet 192.168.10.0/24 --subnet-v6 fd00::/64. Both ranges will be assigned to the network and containers will receive addresses from each family.

What happens if my custom subnet overlaps with an existing network?

The command fails with an error indicating the conflicting range. The Apple Container runtime checks for subnet overlap during creation to ensure that containers on different networks remain isolated unless explicitly connected through routing.

Where are the default subnet configurations stored?

User-specific defaults reside in ~/.config/container/config.toml, while system-wide defaults are located in /etc/container/config.toml. Both use the same TOML structure with a [network] section containing subnet and subnetv6 keys, as defined in the system configuration documentation.

Do changes to the config file affect existing networks?

No. Modifications to either the user or system configuration files only apply to networks created after the change. Existing networks retain their original subnet assignments unless explicitly removed and recreated with new parameters.

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