How to Configure DNS for Containers Using Container System Commands

Container DNS can be configured at both the per-container level using --dns flags and at the system level using container system dns commands, with settings stored in ContainerConfiguration.DNSConfiguration and ContainerSystemConfig.dns respectively.

The apple/container framework provides flexible DNS resolution through two distinct configuration scopes. You can override resolver settings for individual containers at runtime or establish persistent host-side domains that enable seamless container-to-host communication. These configurations are managed through command-line flags, TOML configuration files, and dedicated system commands.

Per-Container DNS Configuration

Use the --dns, --dns-domain, --dns-option, and --dns-search flags when running container run or container create to customize resolution for a specific container instance. These flags are parsed in Sources/Services/ContainerAPIService/Client/Flags.swift and stored in a ContainerConfiguration.DNSConfiguration object. When the container launches, Sources/Services/RuntimeLinux/Server/RuntimeService.swift applies this configuration to the runtime environment.

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

The container will query 8.8.8.8 and 1.1.1.1 for name resolution and append example.com to bare hostnames.

System-Level DNS Configuration

For persistent domain settings across all containers, modify the ~/.config/container/config.toml file. The [dns] section maps to the DNSConfig struct defined in Sources/ContainerPersistence/ContainerSystemConfig.swift, which currently supports an optional domain property.

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

Example configuration:

[dns]
domain = "test"

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

Host-Side DNS Domains for Container-to-Host Communication

The container system dns create command establishes a local macOS resolver entry under /etc/resolver/<domain>, enabling host tools to resolve container hostnames with the specified suffix. When combined with the --localhost flag, this creates a bridge for containers to reach services running on the host.

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

This writes /etc/resolver/host.container.internal pointing to 203.0.113.113. Containers can now resolve http://host.container.internal:8000 to reach a service running on the host.

Managing and Verifying DNS Configuration

List all configured DNS domains:

container system dns list

Verify resolver entries on macOS:

scutil --dns | grep host.container.internal

Summary

• Per-container DNS: Use --dns flags with container run to customize nameservers and search domains for individual containers, with settings stored in ContainerConfiguration.DNSConfiguration.
• System-level domains: Set the domain property in ~/.config/container/config.toml to automatically append suffixes to container hostnames, parsed by ContainerSystemConfig.swift.
• Host-side resolution: Use sudo container system dns create with --localhost to enable container-to-host communication via /etc/resolver entries.
• Configuration sources: DNS settings are managed through ContainerSystemConfig.swift for system config and Flags.swift for runtime parameters.

Frequently Asked Questions

How do I set a custom DNS server for a single container?

Pass the --dns <ip> flag to container run or container create. You can specify multiple servers by repeating the flag. These values populate the DNSConfiguration object in ContainerConfiguration.swift and override the host's resolver for that specific container.

Where is the system-level DNS domain configuration stored?

System-level DNS settings are stored in ~/.config/container/config.toml under the [dns] section. This file is decoded into ContainerSystemConfig (defined in ContainerSystemConfig.swift), which contains a DNSConfig instance with an optional domain property.

How do I enable containers to resolve host services?

Run sudo container system dns create <domain> --localhost <host-ip> to create a resolver entry. This writes to /etc/resolver/<domain> and registers the domain with the macOS DNS cache, allowing containers to resolve the specified domain to the host's IP address.

Can I configure multiple DNS search domains?

Yes. When creating a container, repeat the --dns-search <domain> flag multiple times to specify additional search domains. These are stored in the container's DNSConfiguration and appended to unqualified hostnames during resolution.

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