How to Configure DNS and Network Settings for Containers Managed by apple/container

You can configure DNS and network settings for apple/container by editing the config.toml file for persistent system-wide defaults or using CLI flags like --dns-domain and --subnet for per-container overrides.

The apple/container repository stores global configuration in a TOML file parsed into the ContainerSystemConfig Swift model at runtime. By modifying the DNSConfig and NetworkConfig structs—defined in Sources/ContainerPersistence/ContainerSystemConfig.swift—you control domain resolution, IP addressing, and container reachability from the macOS host.

Understanding the Configuration Architecture

All top-level system configuration resides in config.toml, which the daemon decodes into the ContainerSystemConfig struct. This model contains two primary sub-configurations: DNSConfig for domain resolution and NetworkConfig for subnet allocation. Place this file at $HOME/.container/config.toml for user-specific settings or /etc/container/config.toml for system-wide defaults.

Configuring DNS Settings

DNS configuration controls how container hostnames resolve both inside containers and from the macOS host system.

Setting the Default DNS Domain in config.toml

The DNSConfig struct contains an optional domain: String? property that appends a domain suffix to container hostnames. When configured, a container named my-web-server becomes reachable as my-web-server.<domain> from the host.

Add the following to your config.toml to set a persistent default:

[dns]
domain = "test"

According to the source code in Sources/ContainerPersistence/ContainerSystemConfig.swift, this value initializes the DNS domain for all containers launched without explicit runtime overrides.

Overriding DNS at Runtime with CLI Flags

Override the default domain for individual containers using the --dns-domain flag (or -d shorthand) when executing container run. Specify custom DNS servers with the --dns flag:

container run \
  --dns 192.168.1.53 \
  --dns-domain dev \
  --name my-app \
  ubuntu:latest

This command populates the container's /etc/resolv.conf with the specified nameserver while registering my-app.dev as the resolvable hostname on the host.

Managing Local DNS Domains with the CLI

The CLI provides commands to create host-side DNS resolver entries that map container names to IPs using macOS's resolver system. These operations write to /etc/resolver/<domain> and require sudo privileges.

Create a local DNS domain:

sudo container dns domain add test --ipv4 10.0.0.1

This command creates /etc/resolver/test containing nameserver 10.0.0.1 and registers the domain with macOS via scutil --dns.

Remove a domain:

sudo container dns domain delete test

List all configured domains:

container dns domain list

Configuring Network Settings

Network configuration defines the IP address ranges assigned to container networks, controlled by the NetworkConfig struct in ContainerSystemConfig.swift.

Defining Subnets in config.toml

The NetworkConfig struct accepts optional IPv4 and IPv6 CIDR strings through the subnet and subnetv6 properties. When omitted, the daemon automatically allocates non-overlapping subnets.

Configure persistent subnets in config.toml:

[network]
subnet = "172.20.0.0/16"
subnetv6 = "fd00:dead:beef::/48"

Specifying Subnets Per Container or Network

Override these defaults when creating networks using the --subnet and --subnet-v6 flags:

container network create mynet \
  --subnet 172.20.0.0/16 \
  --subnet-v6 fd00:dead:beef::/48

If you omit these flags, the system selects free CIDR ranges automatically based on current network state.

Practical Configuration Examples

System-Wide Default Configuration

Create /etc/container/config.toml with persistent DNS and network defaults:

[dns]
domain = "internal"

[network]
subnet = "10.100.0.0/16"
subnetv6 = "fd00:10:100::/56"

These values apply to all containers and networks unless explicitly overridden at runtime.

Ad-Hoc Container with Custom DNS

Launch a container with specific DNS overrides without modifying the config file:

container run \
  --dns 8.8.8.8 \
  --dns-domain staging \
  --name web-server \
  nginx:latest

Creating a Local Resolver Entry

Enable hostname resolution for a development domain:

sudo container dns domain add localdev --ipv4 127.0.0.1
container run --dns-domain localdev --name api alpine:latest

The container is now reachable as api.localdev from the host.

Summary

• Configuration File: Edit config.toml (at $HOME/.container/config.toml or /etc/container/config.toml) to set persistent DNS domains and network subnets via the ContainerSystemConfig model.
• DNS Domain: Set the domain field in [dns] section for TOML-based configuration, or use --dns-domain and --dns flags for per-container overrides.
• Network Subnets: Define subnet and subnetv6 in the [network] section, or specify --subnet and --subnet-v6 when creating networks.
• Local Resolution: Use container dns domain add|delete|list commands to manage macOS resolver entries in /etc/resolver/, enabling system-wide hostname resolution for container domains.
• Source Reference: All configuration structures are implemented in Sources/ContainerPersistence/ContainerSystemConfig.swift and documented in docs/container-system-config.md and docs/command-reference.md.

Frequently Asked Questions

Where does apple/container store its configuration file?

The system searches for config.toml in $HOME/.container/config.toml for user-specific settings or /etc/container/config.toml for system-wide defaults. This file maps directly to the ContainerSystemConfig struct defined in Sources/ContainerPersistence/ContainerSystemConfig.swift, which contains the DNSConfig and NetworkConfig sub-models.

How do I make containers reachable by hostname from my Mac?

Use the container dns domain add command to register a local DNS resolver. Executing sudo container dns domain add test --ipv4 10.0.0.1 creates a file at /etc/resolver/test and registers the domain with macOS, allowing resolution of <container-name>.test addresses from the host system.

Can I configure different DNS servers for individual containers?

Yes. While the [dns] section in config.toml sets system-wide defaults, you can override DNS settings per container using the --dns flag to specify nameserver IP addresses and --dns-domain to set the search domain when running container run. These runtime flags map directly to properties in the DNSConfig struct.

What happens if I don't specify a network subnet?

If you omit the subnet and subnetv6 fields from config.toml or omit --subnet flags when creating networks, the apple/container daemon automatically allocates non-overlapping IPv4 and IPv6 CIDR ranges. This automatic allocation is handled by the initialization logic in Sources/ContainerPersistence/ContainerSystemConfig.swift to prevent address conflicts.

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