How to Configure Custom DNS Domains for Containers on macOS

To configure custom DNS domains for containers on macOS, set the domain key in the [dns] section of ~/.config/container/config.toml, then run sudo container dns create <domain> to register the resolver with macOS.

The apple/container repository includes an embedded DNS server that automatically resolves container hostnames on the Mac host. By default, containers are reachable via their names, but you can configure a custom DNS domain—such as myapp.test—to access containers using fully qualified hostnames like web.myapp. This requires updating the Container system configuration and integrating with macOS's resolver infrastructure.

Setting the DNS Domain in the Configuration File

The Container system reads its DNS settings from a TOML configuration file that defines the default domain appended to every container name. This file is parsed by ContainerSystemConfig (located in [Sources/ContainerPersistence/ContainerSystemConfig.swift](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift)).

Create or edit the configuration file at $HOME/.config/container/config.toml to include the [dns] section:

[dns]
domain = "myapp"

With this setting, a container named web automatically becomes resolvable as web.myapp. If the configuration file does not exist, container creates one with defaults on first run.

Registering the Domain with the macOS Resolver

Once the domain is configured, you must register it with macOS so the system resolver knows to query the Container DNS server. The container CLI provides a system command that writes the required resolver file under /etc/resolver/ and reloads the system resolver configuration.

Run the following command to create the resolver entry:

sudo container dns create myapp

This command performs two critical actions: it writes a resolver file containing the address of the internal DNS server (by default 127.0.0.1:53) to /etc/resolver/myapp, then signals mDNSResponder with kill -HUP to pick up the change. The implementation of this system-level integration lives in [Sources/ContainerCommands/System/SystemStart.swift](https://github.com/apple/container/blob/main/Sources/ContainerCommands/System/SystemStart.swift).

Verifying and Managing DNS Domains

After configuration, verify that the domain is active and resolving correctly:

# List all registered container DNS domains

container dns list

# Test resolution of a specific container

ping web.myapp

The container dns list command queries the same configuration state managed by ContainerSystemConfig, ensuring the domain matches what you set in the TOML file.

To remove a custom domain and stop resolution, delete the resolver entry:

sudo container dns delete myapp

This removes the /etc/resolver/myapp file and reloads the macOS resolver.

Complete Configuration Walkthrough

The following commands demonstrate the full workflow from configuration to verification:

# 1. Create the configuration directory and set the DNS domain

mkdir -p $HOME/.config/container
cat > $HOME/.config/container/config.toml <<EOF
[dns]
domain = "myapp"
EOF

# 2. Register the domain with macOS (requires sudo for /etc/resolver/)

sudo container dns create myapp

# 3. Launch a container and test hostname resolution

container run --name web -d nginx
ping web.myapp

When the daemon starts, it loads the configuration from ContainerSystemConfig and passes the DNS settings to the embedded DNS service, which binds to 127.0.0.1:53 by default.

Summary

• Configure the domain by setting the domain key in the [dns] section of $HOME/.config/container/config.toml, parsed by ContainerSystemConfig.swift.
• Register with macOS using sudo container dns create <domain> to write to /etc/resolver/ and signal mDNSResponder.
• Verify resolution with container dns list and standard tools like ping to confirm containers resolve as <name>.<domain>.
• Remove domains using sudo container dns delete <domain> to clean up resolver entries.

Frequently Asked Questions

Where does the container system store its DNS configuration?

The DNS configuration is stored in $HOME/.config/container/config.toml under the [dns] table. The ContainerSystemConfig struct in Sources/ContainerPersistence/ContainerSystemConfig.swift decodes this file at startup, reading the domain key to determine the default DNS suffix for all containers.

Why does creating a DNS domain require sudo privileges?

The container dns create command requires sudo because it writes to the /etc/resolver/ directory, which is protected by macOS system permissions. This directory controls macOS DNS resolution behavior, and modifying it requires administrative access to ensure system security.

How does the container DNS server integrate with macOS system resolution?

The Container DNS server runs on 127.0.0.1:53 and integrates with macOS by placing a resolver file in /etc/resolver/ that points to this address. The CLI then sends a SIGHUP signal to mDNSResponder to reload the resolver configuration without requiring a system reboot, as implemented in the system command handlers.

Can I use multiple custom DNS domains simultaneously?

While the config.toml file supports only one default domain value in the [dns] section, you can create multiple resolver entries by running sudo container dns create <domain> for different domains. However, all containers will share the single domain specified in the configuration file unless you manually manage resolver files for advanced use cases.

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