How to Configure Custom Subnets for Container Networks on macOS

You can configure custom subnets for Apple Container networks by using the --subnet and --subnet-v6 flags when creating a network, or by setting default values in the ~/.config/container/config.toml configuration file.

The Apple Container runtime leverages macOS's vmnet framework to provide network connectivity for containers. By default, the system automatically assigns non-overlapping IPv4 and IPv6 CIDR blocks, but you can explicitly define custom subnets to ensure deterministic addressing or integrate with existing infrastructure. This guide covers the specific methods to configure these subnets at both the network and system level according to the apple/container source code.

Setting Custom Subnets Per Network

When creating a new container network, you can explicitly define the IPv4 and IPv6 ranges using command-line flags. This approach overrides any default settings for that specific network.

Using the --subnet and --subnet-v6 Flags

According to docs/how-to.md (lines 317-322), the container network create command accepts --subnet for IPv4 and --subnet-v6 for IPv6 CIDR notation. The runtime validates that these ranges do not conflict with existing container networks before creation.

# 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 accept standard CIDR notation. After creation, verify the assigned subnets using:

container ls --network frontend

Configuring Default Subnets Globally

To avoid specifying subnets for every new network, you can configure default values in TOML configuration files. The runtime checks these defaults whenever you omit the --subnet or --subnet-v6 flags.

User-Level Configuration

Edit or create the file at ~/.config/container/config.toml to set defaults for your user account. As specified in docs/how-to.md (lines 358-365), use the [network] section with the subnet and subnetv6 keys:

[network]

# Default IPv4 subnet for new networks

subnet = "192.168.100.0/24"

# Default IPv6 subnet for new networks

subnetv6 = "fd00:abcd::/64"

After saving the configuration, any subsequent container network create command that omits explicit subnet flags will automatically use these values. You can verify this by creating a test network and inspecting its configuration:

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

System-Wide Configuration

For multi-user systems, administrators can set defaults in /etc/container/config.toml using the same TOML structure. As documented in docs/container-system-config.md (lines 19-70), this file uses identical [network] section keys (subnet and subnetv6) to define system-wide defaults that apply to all users unless overridden by user-level configs or CLI flags.

Validation and Overlap Detection

The Apple Container runtime implements safeguards to prevent network conflicts. When you specify a custom subnet—whether via CLI or configuration file—the system checks against existing container networks to ensure no overlap exists. If the requested CIDR block conflicts with an active network, the command aborts with an error indicating the specific conflicting range. This ensures that containers on separate networks can only communicate through explicit routing configurations.

Summary

• Per-network configuration: Use --subnet and --subnet-v6 flags with container network create to specify exact CIDR blocks for individual networks.
• Global defaults: Set subnet and subnetv6 keys in the [network] section of ~/.config/container/config.toml for user-level defaults, or /etc/container/config.toml for system-wide defaults.
• Validation: The runtime automatically checks for subnet overlaps and prevents creation of conflicting networks.
• Documentation: Reference docs/how-to.md, docs/container-system-config.md, and docs/command-reference.md in the apple/container repository for authoritative syntax details.

Frequently Asked Questions

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

The Apple Container runtime performs automatic validation when you create a network with custom subnets. If the provided CIDR block overlaps with an existing container network, the container network create command fails immediately with an error message identifying the conflicting range. You can also inspect existing networks using container ls --network <name> to view current subnet allocations before creating new ones.

What configuration file format does Apple Container use?

Apple Container uses TOML (Tom's Obvious, Minimal Language) for configuration files. The user-level config resides at ~/.config/container/config.toml, while system-wide settings are stored in /etc/container/config.toml. Both files use a [network] section containing subnet for IPv4 and subnetv6 for IPv6 CIDR definitions, as defined in docs/container-system-config.md.

Can I set different default subnets for individual users versus system-wide?

Yes. The runtime supports hierarchical configuration: user-level settings in ~/.config/container/config.toml take precedence over system-wide settings in /etc/container/config.toml, which in turn take precedence over built-in defaults. This allows administrators to define baseline subnets in /etc/container/config.toml while permitting individual users to override them with personal configurations.

Does Apple Container support both IPv4 and IPv6 custom subnets?

Yes. The runtime supports dual-stack networking. Use the --subnet flag for IPv4 CIDR notation and --subnet-v6 for IPv6 when creating networks via CLI. In configuration files, set the subnet key for IPv4 and subnetv6 for IPv6. Both can be specified simultaneously to create networks with full dual-stack connectivity.

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