How to Configure Custom DNS Settings for Containers in apple/container

You can configure custom DNS settings for containers in apple/container at two distinct levels: per‑container using --dns, --dns‑search, --dns‑option, and --dns‑domain 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 for Linux containers on macOS. Whether you need specific nameservers for a single container or a custom domain suffix for host‑to‑container resolution, the configuration is handled through CLI flags and TOML configuration files that are parsed into Swift structs defined in the source code.

Configure Per‑Container DNS Settings

Per‑container DNS settings override the default resolver for a specific container instance. These values are stored in ContainerConfiguration.DNSConfiguration as defined in ContainerConfiguration.swift.

Using Runtime Flags

When you create or run a container, pass the DNS‑related flags to specify nameservers, search domains, and resolver options:

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

The CLI parses these arguments in Sources/Services/ContainerAPIService/Client/Flags.swift. The parsed values populate a DNSConfiguration object that is attached to the container’s runtime configuration. When the container launches, Sources/Services/RuntimeLinux/Server/RuntimeService.swift applies this configuration to the container’s network namespace.

Key flags:

• --dns <ip> – Add a custom nameserver (can be specified multiple times).
• --dns-search <domain> – Append a domain to bare hostnames during resolution.
• --dns-option <opt> – Pass arbitrary options to the container’s resolver (e.g., ndots:2).
• --dns-domain <domain> – Set the DNS domain for the container.

Configure System‑Wide DNS Domains

System‑wide DNS configuration affects how the macOS host resolves container hostnames and how containers reach services on the host. This is controlled by the ContainerSystemConfig struct in Sources/ContainerPersistence/ContainerSystemConfig.swift.

Via Configuration File

Create or edit ~/.config/container/config.toml to set a default domain suffix for all containers:

[dns]
domain = "test"

The TOML decoder maps this to the DNSConfig class, which is defined as:

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

With this setting, a container named my-web-server becomes reachable from the macOS host as my-web-server.test. The domain is stored in ContainerSystemConfig.dns and persisted across daemon restarts.

Via Command Line (container system dns)

For scenarios requiring host‑to‑container or container‑to‑host DNS resolution, use the container system dns subcommand. This creates a resolver entry under /etc/resolver/<domain> (requires sudo):

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

This command registers the domain with the macOS DNS cache so that any hostname ending with that domain is forwarded to the container’s virtual network. When the --localhost flag is supplied, the specified IPv4 address becomes the A record for the domain, enabling containers to resolve the host machine (documented in docs/how-to.md).

Verify the resolver entry:

scutil --dns | grep host.container.internal

List all configured domains:

container system dns list

Architecture Overview

The DNS configuration system relies on two distinct models that interact at runtime:

1. DNSConfig – Defined in ContainerSystemConfig.swift, this struct handles the global [dns] TOML configuration. It currently supports an optional domain string that appends a suffix to all container hostnames.

2. ContainerConfiguration.DNSConfiguration – Defined in ContainerConfiguration.swift, this struct stores per‑container overrides passed via CLI flags. It is instantiated in Flags.swift and consumed by RuntimeService.swift when launching the container runtime.

When a container starts, the runtime merges these configurations: the system‑wide domain provides the default search suffix, while per‑container flags override specific resolver behavior for that instance.

Practical Examples

Set Multiple Nameservers for a Database Container

container run --dns 8.8.8.8 --dns 8.8.4.4 \
    --dns-search internal.company.com \
    --name postgres \
    postgres:15

Enable Host Service Access from Containers

# On macOS host

sudo container system dns create host.docker.internal \
    --localhost 192.168.1.100

# Inside container

curl http://host.docker.internal:8080/api/health

Configure Global Domain for Development

Edit ~/.config/container/config.toml:

[dns]
domain = "dev.local"

Now every container is accessible via <container-name>.dev.local from the terminal.

Summary

• Per‑container DNS is configured via --dns, --dns‑search, --dns‑option, and --dns‑domain flags parsed in Flags.swift and applied in RuntimeService.swift.
• System‑wide DNS domains are configured in ~/.config/container/config.toml under the [dns] section, decoded by ContainerSystemConfig.swift.
• Host resolver integration requires sudo container system dns create to write entries to /etc/resolver, enabling macOS to resolve container hostnames.
• Container‑to‑host communication is enabled by passing --localhost <ip> to the DNS creation command, creating an A record pointing to the host.

Frequently Asked Questions

How do I override DNS settings for just one container?

Use the --dns and --dns‑search flags with container run or container create. These values are stored in the container’s DNSConfiguration object and override the system defaults for that specific container instance.

Where does apple/container store the global DNS domain setting?

The global setting is stored in ~/.config/container/config.toml under the [dns] key. The file is parsed into the ContainerSystemConfig struct, specifically the dns property which holds a DNSConfig instance containing the domain string.

Can containers resolve services running on the macOS host?

Yes. Run sudo container system dns create <domain> --localhost <host-ip> to create a resolver entry that points the custom domain to your host’s IP address. Containers can then resolve <domain> to reach host services.

What is the difference between --dns-search and --dns-domain?

--dns-search adds domains to the resolver’s search list for hostname expansion, while --dns-domain sets the single DNS domain for the container. Both are part of the per‑container DNSConfiguration and are processed by the runtime when the container network namespace is configured.

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