How to Configure DNS Domains for Host Connections in Apple Container

Use the container system dns command to register a domain with macOS, set a system-wide default in config.toml, or override per-container with the --dns-domain flag.

The apple/container repository provides an embedded DNS service that bridges container networking to the macOS host. Configuring DNS domains for host connections enables hostname resolution from the host to containers using custom suffixes rather than IP addresses. This integration works through three distinct layers: system-wide configuration, CLI-managed resolver files, and per-container runtime flags.

System-Wide DNS Configuration

The global DNS behavior is defined in the top-level config.toml under the [dns] section. The domain key supplies a suffix that is automatically appended to every container name, creating fully qualified domain names resolvable from the host.

The DNSConfig Implementation

According to the source code in Sources/ContainerPersistence/ContainerSystemConfig.swift, the DNSConfig class (lines 34-41) defines the structure for system-wide DNS settings. This configuration persists across container restarts and applies to all containers unless explicitly overridden.

Configuring the Domain Suffix

Add the following to your config.toml:

[dns]
domain = "test"

With this setting, a container started with --name my-web-server becomes reachable as my-web-server.test from the macOS host. The embedded DNS server automatically resolves this name to the container's virtual IP address.

Managing DNS Domains via CLI

On macOS, the tool creates resolver files under /etc/resolver/ and reloads the system DNS cache. This bridges the gap between the container runtime and the host's resolver subsystem.

Creating a DNS Domain

Use the system dns subcommand to register a new domain:

sudo container system dns create test

This writes a file at /etc/resolver/test and triggers a DNS reload, as documented in docs/tutorials/start-here.md (lines 8-14). Verify the configuration using:

scutil --dns | grep 'domain : test'

Removing a DNS Domain

To unregister a domain and remove its resolver file:

sudo container system dns delete test

Per-Container DNS Overrides

Individual containers can override the system-wide domain or specify their own using runtime flags.

Using the --dns-domain Flag

As implemented in Sources/Services/ContainerAPIService/Client/Flags.swift (lines 19-40), the --dns-domain option allows per-container customization:

container run --name db --dns-domain custom.local my-db-image

The host can now reach this container at db.custom.local, regardless of the system default.

Validation Rules

The source code validates that --no-dns cannot be combined with DNS-related flags. The validate() method ensures mutual exclusivity between disabling DNS and specifying custom domains, preventing configuration conflicts.

Complete Configuration Example

Combine these layers to set up a working DNS resolution workflow:

# 1. Create a local DNS domain called "test"

sudo container system dns create test

# 2. Run a container with automatic hostname suffixing

container run --name my-web-server --detach --rm \
    --publish 8080:80 \
    my-image

# 3. Verify resolution from the host

ping my-web-server.test

# 4. Run a container with a custom domain override

container run --name db --dns-domain custom.local my-db-image

# 5. Access the overridden container

ping db.custom.local

When the system domain is test and you launch a container named my-web-server, the embedded DNS server appends the suffix and resolves my-web-server.test to the container's virtual IP (typically in the 192.168.64.x range).

Summary

• System configuration: Define a default domain in config.toml under the [dns] section, implemented in Sources/ContainerPersistence/ContainerSystemConfig.swift.
• CLI management: Use sudo container system dns create <domain> to write resolver files to /etc/resolver/ and register domains with macOS.
• Per-container overrides: Specify --dns-domain for individual containers, validated in Sources/Services/ContainerAPIService/Client/Flags.swift.
• Resolution flow: The host's resolver sees the custom domain, the runtime appends the suffix, and the embedded DNS server maps hostnames to virtual IPs.

Frequently Asked Questions

How do I verify that my DNS domain is active on macOS?

Check the resolver configuration using scutil --dns and grep for your domain name. You should see an entry pointing to the container's DNS server. If the domain is missing, ensure you ran sudo container system dns create with administrative privileges.

Can I use multiple DNS domains simultaneously?

Yes. You can create multiple resolver files using container system dns create for different domains, and containers can use different domains via the --dns-domain flag. However, each container can only have one domain suffix applied to its hostname at runtime.

What happens if I specify --dns-domain but the system config has a different domain?

The --dns-domain flag overrides the system-wide setting from config.toml for that specific container. The per-container flag takes precedence, allowing you to mix containers with different domain suffixes on the same host.

Where does the container tool store DNS configuration on macOS?

The system domain is stored in the user's config.toml. Runtime domains are registered in /etc/resolver/<domain> files managed by the CLI commands. The DNSConfig struct in Sources/ContainerPersistence/ContainerSystemConfig.swift defines the in-memory representation of these settings.

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