How to Configure DNS Settings for Containers in Apple’s Container Framework

Container DNS settings can be configured at the per-container level using --dns flags or system-wide via the [dns] section in ~/.config/container/config.toml and the container system dns create command.

The Apple Container framework provides flexible DNS resolution through two distinct configuration scopes. You can define nameservers for individual containers at runtime or establish system-wide domains that enable host-to-container and container-to-host communication. This guide covers the implementation details based on the apple/container source code.

Per-Container DNS Configuration

Configure DNS for individual containers using command-line flags when running or creating containers. The CLI parses these flags in Sources/Services/ContainerAPIService/Client/Flags.swift and stores them in ContainerConfiguration.DNSConfiguration as defined in Sources/ContainerResource/Container/ContainerConfiguration.swift.

Runtime DNS Flags

The following flags are available for the container run and container create commands:

• --dns <ip>: Specify a custom nameserver IP address (can be used multiple times)
• --dns-search <domain>: Set DNS search domains
• --dns-domain <domain>: Set the DNS domain name
• --dns-option <opt>: Set resolver options

When a container is launched, these values are applied to the container's runtime configuration in Sources/Services/RuntimeLinux/Server/RuntimeService.swift.

container run --dns 8.8.8.8 --dns 1.1.1.1 \
    --dns-search example.com \
    alpine:latest

This configuration causes the container to query 8.8.8.8 and 1.1.1.1 for name resolution and append example.com to bare hostnames.

System-Wide DNS Configuration

For persistent settings that apply across all containers, use the TOML configuration file or system DNS commands. These settings interact with the macOS resolver and enable hostname resolution between the host and containers.

Configuring the DNS Domain in config.toml

The top-level configuration file at ~/.config/container/config.toml is decoded into ContainerSystemConfig in Sources/ContainerPersistence/ContainerSystemConfig.swift. The [dns] section maps to the DNSConfig class:

final public class DNSConfig: Codable, Sendable {
    public let domain: String?
    public init(domain: String? = nil) { self.domain = domain }
}

To append a default domain to all container hostnames, add the following to your configuration file:

[dns]
domain = "test"

With this setting, a container named my-web-server becomes reachable as my-web-server.test from the host.

Creating Host-Side DNS Domains

Use the container system dns create command to register domains with the macOS DNS resolver. This command writes a resolver file under /etc/resolver/<domain> and requires sudo privileges.

To create a domain that resolves to the host machine (enabling container-to-host communication), use the --localhost flag:

sudo container system dns create host.container.internal \
    --localhost 203.0.113.113

This configuration allows containers to reach services on the host using the domain host.container.internal, which resolves to 203.0.113.113.

Verifying DNS Configuration

Verify that host-side DNS domains are correctly registered using the macOS system configuration utility:

scutil --dns | grep host.container.internal

To view all configured system-wide DNS domains:

container system dns list

This command displays all domains created via container system dns create.

Summary

• Per-container DNS is configured via --dns, --dns-search, --dns-domain, and --dns-option flags, parsed in Flags.swift and stored in ContainerConfiguration.DNSConfiguration
• System-wide DNS domains are defined in the [dns] section of ~/.config/container/config.toml and decoded by ContainerSystemConfig in ContainerSystemConfig.swift
• Host-side resolver entries are created with sudo container system dns create and stored in /etc/resolver/, enabling domain resolution between host and containers
• Container-to-host networking is enabled by specifying --localhost <ipv4> when creating a system DNS domain

Frequently Asked Questions

What is the difference between per-container and system-wide DNS configuration?

Per-container settings apply only to the specific container instance using runtime flags, while system-wide settings in config.toml or created via container system dns create affect how the host resolves container names and how containers resolve host services. The per-container configuration is stored in ContainerConfiguration.DNSConfiguration, whereas system-wide configuration is managed through ContainerSystemConfig and the macOS resolver.

Where does the Apple Container framework store DNS configuration files?

Per-container DNS settings are stored in the container's runtime configuration through ContainerConfiguration.DNSConfiguration. System-wide configuration is stored in ~/.config/container/config.toml for the [dns] domain setting. Host-side DNS domains require sudo and write resolver configuration files to /etc/resolver/<domain>.

How do I enable containers to resolve services running on the host?

Use sudo container system dns create <domain> --localhost <ipv4> to create a DNS entry that resolves to the host's IP address. For example, sudo container system dns create host.container.internal --localhost 203.0.113.113 allows containers to reach host services at http://host.container.internal:8000. This mechanism is documented in docs/how-to.md in the repository.

Do I need special permissions to configure DNS in Apple Container?

Per-container DNS flags (--dns, --dns-search, etc.) work without elevated privileges. However, system-wide configuration using container system dns create requires sudo because it writes to the /etc/resolver/ directory and modifies system-level DNS settings on macOS.

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