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

> Learn how to configure custom DNS settings for containers in apple/container. Control DNS per-container with flags or system-wide using config files and commands.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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`](https://github.com/apple/container/blob/main/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:

```bash
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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift)**.

### Via Configuration File

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

```toml
[dns]
domain = "test"

```

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

```swift
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`):

```bash
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`](https://github.com/apple/container/blob/main/docs/how-to.md)**).

Verify the resolver entry:

```bash
scutil --dns | grep host.container.internal

```

List all configured domains:

```bash
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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/ContainerConfiguration.swift)**, this struct stores per‑container overrides passed via CLI flags. It is instantiated in **[`Flags.swift`](https://github.com/apple/container/blob/main/Flags.swift)** and consumed by **[`RuntimeService.swift`](https://github.com/apple/container/blob/main/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

```bash
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

```bash

# 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`:

```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`](https://github.com/apple/container/blob/main/Flags.swift)** and applied in **[`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift)**.
- **System‑wide DNS domains** are configured in `~/.config/container/config.toml` under the `[dns]` section, decoded by **[`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/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.