How to Configure Custom Subnets for Container Networks in Apple Container

Use the --subnet and --subnet-v6 flags when creating individual networks, or set the subnet and subnetv6 keys in the [network] section of ~/.config/container/config.toml to define global defaults for all new container networks.

Container networking in the Apple Container runtime leverages macOS's vmnet framework to provide IPv4 and IPv6 connectivity for isolated workloads. While the system automatically assigns non-overlapping CIDR blocks when you create networks, production environments often require specific IP ranges for service discovery, firewall rules, or corporate network integration. This guide explains how to configure custom subnets for container networks using both CLI flags and configuration files, based on the official apple/container repository documentation.

Per-Network Subnet Configuration with CLI Flags

When you need a specific CIDR block for a single network, pass explicit flags to the container network create command. According to the command reference in docs/command-reference.md (lines 777-791), the --subnet flag accepts an IPv4 CIDR, while --subnet-v6 accepts an IPv6 CIDR.

Creating a Network with Custom IPv4 and IPv6 Subnets

The following example creates a network named "frontend" with a custom IPv4 /24 and IPv6 /64 range:

# Create a network with explicit IPv4 and IPv6 subnets

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

As documented in docs/how-to.md (lines 317-322), these flags override any default settings and assign the specified ranges immediately upon network creation.

Verifying Assigned Subnets

After creation, inspect the network to confirm the assigned ranges:

container ls --network frontend

The output displays the network name and the CIDR blocks that containers attached to this network will receive.

Global Default Subnet Configuration

To avoid specifying subnets for every new network, configure default values in TOML configuration files. The runtime checks for settings in two locations: user-level configuration at ~/.config/container/config.toml and system-wide configuration at /etc/container/config.toml.

User-Level Configuration

Create or edit ~/.config/container/config.toml to set defaults for your user account. As specified in docs/how-to.md (lines 358-365) and the system configuration reference in docs/container-system-config.md (lines 19-70), use the [network] section with the subnet and subnetv6 keys:

[network]

# Default IPv4 subnet for networks created without an explicit --subnet flag

subnet = "192.168.100.0/24"

# Default IPv6 subnet for networks created without an explicit --subnet-v6 flag

subnetv6 = "fd00:abcd::/64"

System-Wide Configuration

For multi-user systems, administrators can place the same [network] configuration in /etc/container/config.toml. This applies the default subnets to all users on the system unless overridden by explicit CLI flags or user-level config files.

Verifying Default Configuration

After saving the configuration file, create a network without subnet flags to verify the defaults apply:

container network create internal-net
container ls --network internal-net

The output should show 192.168.100.0/24 for IPv4 and fd00:abcd::/64 for IPv6, confirming the settings from config.toml are active.

Subnet Validation and Overlap Detection

When you provide a custom subnet, the Apple Container runtime validates that the CIDR block does not overlap with existing container networks. If the check detects a conflict, the command aborts with an error indicating the colliding range. This safeguard ensures that containers on different networks can reach each other only through explicit routing, preventing accidental IP address collisions.

Use Cases for Custom Subnets

Configuring explicit subnets provides several operational benefits:

• Deterministic addressing: Use known IP ranges for services that expect static addresses or hardcoded firewall rules.
• Infrastructure integration: Align container subnets with your corporate IP plan to simplify routing between container workloads and existing physical networks.
• Conflict prevention: On hosts running many networks, pre-assigning non-overlapping CIDRs prevents the automatic allocator from selecting ranges that collide with VPN clients or other network interfaces.

Summary

• Use --subnet and --subnet-v6 flags with container network create to configure custom subnets for individual networks
• Set global defaults by editing ~/.config/container/config.toml or /etc/container/config.toml with [network] section keys subnet and subnetv6
• The runtime validates custom subnets against existing networks to prevent overlapping CIDR blocks
• Custom subnets enable deterministic IP addressing and integration with existing infrastructure

Frequently Asked Questions

What is the default subnet range for container networks?

By default, the Apple Container runtime automatically selects non-overlapping IPv4 and IPv6 CIDR blocks from private ranges when creating networks. The specific ranges are chosen dynamically by the macOS vmnet framework to avoid conflicts with existing host networks.

How do I check if a custom subnet overlaps with existing networks?

The runtime automatically performs overlap detection when you specify a custom subnet. If you attempt to create a network with a CIDR block that conflicts with an existing container network, the command aborts and displays an error indicating the conflicting range. You can also manually inspect existing networks using container ls --network <name> to view their assigned ranges before creating new ones.

Can I customize subnets for existing networks?

No, you cannot modify the subnet configuration of an existing network after creation. To use a different subnet, you must create a new network with the desired CIDR block using container network create with the appropriate flags, then migrate containers to the new network.

Where is the network configuration stored on macOS?

User-specific default subnets are stored in ~/.config/container/config.toml, while system-wide defaults reside in /etc/container/config.toml. Both files use TOML format with a [network] section containing subnet and subnetv6 keys. Per-network configurations are stored internally by the runtime and managed through the container network CLI commands.

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