How to Configure Custom DNS Servers and Options for Containers in Apple Container

The apple/container CLI provides five DNS-specific flags—--dns, --dns-domain, --dns-search, --dns-option, and --no-dns—that map to the Flags.DNS structure and persist into ContainerConfiguration.DNSConfiguration, defaulting to Cloudflare's 1.1.1.1 nameserver when unspecified.

The apple/container repository offers granular control over DNS resolution for containerized workloads through command-line interface options. When you configure custom DNS servers and options for containers, the system validates your input against strict mutual exclusion rules before persisting the configuration into the container model. This implementation ensures predictable name resolution behavior whether you are running ephemeral workloads or configuring persistent builder environments.

Available DNS Configuration Flags

The container command supports the following flags to customize resolver behavior inside containers:

• --dns <ip> — Specify one or more nameserver IP addresses. The default value is 1.1.1.1 when omitted.
• --dns-domain <domain> — Set the default search domain for the container's resolver.
• --dns-search <domain> — Append additional search domains as comma-separated values.
• --dns-option <option> — Pass resolver options such as debug or ndots:5 to the container's DNS configuration.
• --no-dns — Disable all DNS configuration entirely. This flag cannot be combined with any other DNS-related flags.

Runtime DNS Configuration Examples

Use the container run command to apply custom DNS settings to ephemeral containers. The flags populate the ContainerConfiguration.DNSConfiguration struct before the container starts.

Configure multiple nameservers and a default domain:

container run \
  --dns 8.8.8.8 \
  --dns 8.8.4.4 \
  --dns-domain mycorp.local \
  alpine:latest \
  cat /etc/resolv.conf

Add search domains and resolver options while retaining the default nameserver:

container run \
  --dns-option ndots:5 \
  --dns-search dev.example.com,svc.example.com \
  ubuntu:latest \
  sh -c 'cat /etc/resolv.conf'

Attempting to mix --no-dns with other flags triggers a validation error:

# This command will fail

container run \
  --no-dns \
  --dns-search dev.example.com \
  alpine:latest

Builder Container DNS Settings

DNS configuration applies consistently to builder containers via the container builder start command, utilizing the same Flags.DNS parsing logic:

container builder start \
  --dns 10.0.0.53 \
  --dns-domain internal \
  --dns-search svc.internal,apps.internal

Source Code Implementation

CLI Flag Parsing

The DNS flag definitions reside in Sources/Services/ContainerAPIService/Client/Flags.swift at lines 129–151, where the Flags.DNS struct captures user input. This structure gathers arrays for nameservers and search domains alongside individual option strings.

Validation logic at lines 350–363 enforces mutual exclusion: when --no-dns is present, the code verifies that no other DNS flags appear in the command invocation. If conflicting flags are detected, the parser raises a validation error before container creation proceeds.

Container Configuration Model

Parsed DNS values transfer into Sources/ContainerResource/Container/ContainerConfiguration.swift, specifically into the optional dns property defined at lines 30–38. The ContainerConfiguration.DNSConfiguration struct stores four fields:

• nameservers: Array of IP address strings
• domain: Single default search domain string
• searchDomains: Array of additional search domains
• options: Array of resolver option strings

The default nameserver constant appears at line 31 as ["1.1.1.1"], which the system applies when the configuration object is absent or uninitialized.

Validation Constraints and Defaults

The implementation enforces two critical constraints:

1. Mutual Exclusion: The --no-dns flag validates in isolation. Supplying --no-dns alongside --dns, --dns-domain, --dns-search, or --dns-option causes immediate command failure.
2. Default Fallback: Without any DNS flags, containers automatically receive a DNSConfiguration instance containing only 1.1.1.1 as the nameserver.

Summary

• The apple/container CLI exposes five flags for DNS customization: --dns, --dns-domain, --dns-search, --dns-option, and --no-dns.
• Flag parsing occurs in Sources/Services/ContainerAPIService/Client/Flags.swift, with validation preventing --no-dns from combining with other DNS options.
• Configuration persists into ContainerConfiguration.DNSConfiguration defined in Sources/ContainerResource/Container/ContainerConfiguration.swift.
• The default nameserver is hardcoded as 1.1.1.1 and applies when no DNS flags are provided.
• DNS settings work identically for both container run and container builder start commands.

Frequently Asked Questions

What is the default DNS server if I don't specify any flags?

According to the source code in Sources/ContainerResource/Container/ContainerConfiguration.swift at line 31, the system defaults to ["1.1.1.1"] (Cloudflare DNS) when no DNS configuration flags are present. This value populates the nameservers array automatically.

Can I use --no-dns with other DNS flags?

No. The validation logic in Sources/Services/ContainerAPIService/Client/Flags.swift (lines 350–363) explicitly checks for this combination and raises a validation error if --no-dns appears alongside --dns, --dns-domain, --dns-search, or --dns-option.

How do I add multiple search domains to a container?

Use the --dns-search flag with comma-separated domain values. For example: --dns-search dev.example.com,svc.example.com. These values populate the searchDomains array within the ContainerConfiguration.DNSConfiguration struct.

Where is the DNS configuration stored in the container model?

The DNS configuration is stored in the optional dns property of the container configuration object, typed as ContainerConfiguration.DNSConfiguration. This struct is defined in Sources/ContainerResource/Container/ContainerConfiguration.swift at lines 30–38 and contains the nameservers, domain, searchDomains, and options fields.

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