# How to Configure DNS Settings for Containers in Apple’s Container Framework

> Learn how to configure DNS settings for containers in Apple’s Container framework. Master per-container and system-wide DNS configurations for optimal network performance.

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

---

**Container DNS settings can be configured at the per-container level using `--dns` 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 through two distinct configuration scopes. You can define nameservers for individual containers at runtime or establish system-wide domains that enable host-to-container and container-to-host communication. This guide covers the implementation details based on the `apple/container` source code.

## Per-Container DNS Configuration

Configure DNS for individual containers using command-line flags when running or creating containers. The CLI parses these flags in [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) and stores them in `ContainerConfiguration.DNSConfiguration` as defined in [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift).

### Runtime DNS Flags

The following flags are available for the `container run` and `container create` commands:

- `--dns <ip>`: Specify a custom nameserver IP address (can be used multiple times)
- `--dns-search <domain>`: Set DNS search domains
- `--dns-domain <domain>`: Set the DNS domain name
- `--dns-option <opt>`: Set resolver options

When a container is launched, these values are applied to the container's runtime configuration in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift).

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

```

This configuration causes the container to query `8.8.8.8` and `1.1.1.1` for name resolution and append `example.com` to bare hostnames.

## System-Wide DNS Configuration

For persistent settings that apply across all containers, use the TOML configuration file or system DNS commands. These settings interact with the macOS resolver and enable hostname resolution between the host and containers.

### Configuring the DNS Domain in config.toml

The top-level configuration file at `~/.config/container/config.toml` is decoded into `ContainerSystemConfig` in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift). The `[dns]` section maps to the `DNSConfig` class:

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

```

To append a default domain to all container hostnames, add the following to your configuration file:

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

```

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

### Creating Host-Side DNS Domains

Use the `container system dns create` command to register domains with the macOS DNS resolver. This command writes a resolver file under `/etc/resolver/<domain>` and requires `sudo` privileges.

To create a domain that resolves to the host machine (enabling container-to-host communication), use the `--localhost` flag:

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

```

This configuration allows containers to reach services on the host using the domain `host.container.internal`, which resolves to `203.0.113.113`.

## Verifying DNS Configuration

Verify that host-side DNS domains are correctly registered using the macOS system configuration utility:

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

```

To view all configured system-wide DNS domains:

```bash
container system dns list

```

This command displays all domains created via `container system dns create`.

## Summary

- **Per-container DNS** is configured via `--dns`, `--dns-search`, `--dns-domain`, and `--dns-option` flags, parsed in [`Flags.swift`](https://github.com/apple/container/blob/main/Flags.swift) and stored in `ContainerConfiguration.DNSConfiguration`
- **System-wide DNS domains** are defined in the `[dns]` section of `~/.config/container/config.toml` and decoded by `ContainerSystemConfig` in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift)
- **Host-side resolver entries** are created with `sudo container system dns create` and stored in `/etc/resolver/`, enabling domain resolution between host and containers
- **Container-to-host networking** is enabled by specifying `--localhost <ipv4>` when creating a system DNS domain

## Frequently Asked Questions

### What is the difference between per-container and system-wide DNS configuration?

Per-container settings apply only to the specific container instance using runtime flags, while system-wide settings in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) or created via `container system dns create` affect how the host resolves container names and how containers resolve host services. The per-container configuration is stored in `ContainerConfiguration.DNSConfiguration`, whereas system-wide configuration is managed through `ContainerSystemConfig` and the macOS resolver.

### Where does the Apple Container framework store DNS configuration files?

Per-container DNS settings are stored in the container's runtime configuration through `ContainerConfiguration.DNSConfiguration`. System-wide configuration is stored in `~/.config/container/config.toml` for the `[dns]` domain setting. Host-side DNS domains require `sudo` and write resolver configuration files to `/etc/resolver/<domain>`.

### How do I enable containers to resolve services running on the host?

Use `sudo container system dns create <domain> --localhost <ipv4>` to create a DNS entry that resolves to the host's IP address. For example, `sudo container system dns create host.container.internal --localhost 203.0.113.113` allows containers to reach host services at `http://host.container.internal:8000`. This mechanism is documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) in the repository.

### Do I need special permissions to configure DNS in Apple Container?

Per-container DNS flags (`--dns`, `--dns-search`, etc.) work without elevated privileges. However, system-wide configuration using `container system dns create` requires `sudo` because it writes to the `/etc/resolver/` directory and modifies system-level DNS settings on macOS.