# How to Configure DNS for Containers Using Container System Commands

> Learn to configure container DNS using container system commands. Set DNS at per-container or system levels, storing configurations in ContainerConfiguration and ContainerSystemConfig.

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

---

**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`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) and stored in a `ContainerConfiguration.DNSConfiguration` object. 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 runtime environment.

```bash
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`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), which currently supports an optional `domain` property.

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

```

Example configuration:

```toml
[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.

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

```bash
container system dns list

```

Verify resolver entries on macOS:

```bash
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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) for system config and [`Flags.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.