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

You configure DNS and network settings for containers managed by apple/container through a TOML configuration file at ~/.container/config.toml or /etc/container/config.toml, with optional runtime overrides via the --dns-domain, --subnet, and --subnet-v6 CLI flags.

The apple/container repository provides a Swift-based container runtime that centralizes system configuration in a single ContainerSystemConfig model. This architecture allows you to define persistent DNS domains and network subnets globally while retaining the flexibility to override them per container at launch time.

Configuration File Structure

All top-level settings are stored in config.toml and parsed into the ContainerSystemConfig Swift struct defined in Sources/ContainerPersistence/ContainerSystemConfig.swift. The file uses standard TOML syntax with dedicated sections for DNS and network parameters.

DNS Configuration (DNSConfig)

The DNSConfig struct contains a single optional field domain: String? that controls the default DNS domain appended to container hostnames.

When domain is set, containers become reachable as <container-name>.<domain> from the host. If the field is nil, no domain suffix is added.

Global configuration in config.toml:

[dns]
domain = "test"

This setting persists across all containers unless overridden at runtime. The ContainerSystemConfig initializer reads this value from the TOML [dns] section and stores it in the DNSConfig.domain property.

Network Configuration (NetworkConfig)

The NetworkConfig struct manages IP addressing through two optional CIDR string fields: subnet (IPv4) and subnetv6 (IPv6).

When omitted, the daemon automatically allocates non-overlapping subnets. Explicitly defining these prevents automatic allocation and ensures consistent addressing across container restarts.

Global configuration in config.toml:

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

These values map directly to NetworkConfig.subnet and NetworkConfig.subnetv6 in the Swift source, as implemented in Sources/ContainerPersistence/ContainerSystemConfig.swift.

Runtime CLI Overrides

The container run and container network create commands accept flags that override config.toml settings for specific containers or networks.

DNS Flags

Use the --dns-domain (or -d) flag to specify a domain suffix at runtime:

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

This makes the container reachable as my-app.dev from the host, regardless of the global config.toml setting. The flag updates the DNSConfig domain property for this specific container instance.

Network Flags

Specify custom subnets when creating networks:

container network create mynet \
  --subnet 172.30.0.0/16 \
  --subnet-v6 fd00:cafe::/48

These flags populate the NetworkConfig fields at creation time, bypassing automatic subnet allocation.

Managing Local DNS Domains

The container daemon can create host-side DNS resolvers that map container names to their IPs using macOS's resolver system. This requires writing to /etc/resolver/ and registering with scutil.

Adding DNS Domains

Create a local DNS domain that resolves container names to specific IPs:

sudo container dns domain add test --ipv4 10.0.0.1

This command performs two operations:

1. Writes a resolver file to /etc/resolver/test containing nameserver 10.0.0.1
2. Registers the domain with the macOS resolver via scutil --dns

Listing and Removing Domains

View all configured domains:

container dns domain list

Example output:

test      10.0.0.1
dev       192.168.1.53

Remove a domain and its resolver configuration:

sudo container dns domain delete test

This deletes the file at /etc/resolver/test and updates the system resolver configuration.

Complete Configuration Examples

Global config.toml Setup

Create a system-wide configuration that applies to all containers:

# ~/.container/config.toml or /etc/container/config.toml

[dns]
domain = "internal"

[network]
subnet = "10.0.0.0/16"
subnetv6 = "fd00::/48"

With this configuration, every container launched without explicit flags receives the internal domain suffix and operates within the 10.0.0.0/16 subnet.

Per-Container Overrides

Launch a container with custom DNS and network settings:

container run \
  --dns 192.168.1.53 \
  --dns-domain dev \
  --subnet 172.20.0.0/24 \
  --name web-server \
  nginx:latest

This container:

• Uses 192.168.1.53 as its DNS server (written to /etc/resolv.conf inside the container)
• Is reachable as web-server.dev from the host
• Operates on the 172.20.0.0/24 network segment

Summary

• Configuration location: Edit ~/.container/config.toml or /etc/container/config.toml to set system-wide defaults.
• DNS domain: Set [dns] domain in TOML or use --dns-domain at runtime to append domain suffixes to container hostnames.
• Network subnets: Define [network] subnet and subnetv6 in TOML or use --subnet and --subnet-v6 flags to control IP addressing.
• Local resolver: Use sudo container dns domain add <domain> --ipv4 <addr> to create host-side DNS entries in /etc/resolver/.
• Source files: Sources/ContainerPersistence/ContainerSystemConfig.swift defines the DNSConfig and NetworkConfig structs that parse these settings.

Frequently Asked Questions

Where does apple/container store its configuration files?

The runtime searches for config.toml in two locations: $HOME/.container/config.toml for user-specific settings and /etc/container/config.toml for system-wide configuration. Values in the user home directory override system defaults. Both files are parsed into the ContainerSystemConfig Swift model at daemon startup.

How do I make containers reachable by hostname from the macOS host?

Create a local DNS domain using sudo container dns domain add <domain> --ipv4 <nameserver-ip>. This writes a resolver file to /etc/resolver/<domain> and registers the domain with macOS via scutil. Combined with the --dns-domain flag when running containers, this enables hostname resolution like my-container.test from the host.

What happens if I don't specify a subnet in config.toml?

If NetworkConfig.subnet or subnetv6 are nil in the configuration file, the apple/container daemon automatically allocates a non-overlapping subnet from the private address space. This automatic allocation occurs in the Swift runtime when the network configuration is initialized without explicit CIDR values.

Can I use different DNS settings for each container?

Yes. While the [dns] domain setting in config.toml provides a global default, you can override it per container using the --dns-domain <domain> flag with container run. Additionally, use --dns <ip> to specify custom DNS servers for individual containers, which populate /etc/resolv.conf inside the container filesystem.

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