# How to Configure Host DNS for Containers on macOS Using the Container Tool

> Learn to configure host DNS for containers on macOS using the container tool. Explore options like passing flags or creating persistent resolver domains for seamless networking.

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

---

**On macOS, you configure host DNS for containers by either passing `--dns` flags to individual containers or creating a persistent resolver domain via `container system dns create` and the `[dns]` section in `~/.config/container/config.toml`.**

The `apple/container` repository provides a native macOS container runtime that integrates with the host’s DNS resolution system. Unlike Linux, macOS requires specific resolver configuration to allow host-to-container and container-to-host name resolution, which this tool handles through system-level DNS entries and per-container runtime settings.

## Per-Container DNS Configuration

Individual containers can override default DNS behavior using runtime flags. 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 a `ContainerConfiguration.DNSConfiguration` object defined in [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift).

When launching a container, the runtime applies these settings as shown in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift).

Available flags include:

- `--dns <ip>` – Specify nameserver IP addresses
- `--dns-domain <domain>` – Set the DNS domain
- `--dns-option <opt>` – Pass resolver options
- `--dns-search <domain>` – Configure search domains

Configure a container with custom nameservers:

```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 resolution and append `example.com` to bare hostnames.

## System-Level Host DNS Configuration

For persistent DNS configuration that affects how the macOS host resolves container names, the tool supports two methods: configuration file entries and command-line domain creation.

### Configuring via config.toml

The top-level configuration file at `~/.config/container/config.toml` decodes into `ContainerSystemConfig` (see [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift)). The `dns` property uses the `DNSConfig` struct:

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

```

Add a default domain to all containers by editing `~/.config/container/config.toml`:

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

```

With this setting, `my-web-server` becomes reachable as `my-web-server.test` from the host, and `container ls` displays the full hostname.

### Creating a Host-Side DNS Domain

The `container system dns create` command generates a macOS resolver file under `/etc/resolver/<domain>`. This requires `sudo` privileges and registers the domain with the macOS DNS cache.

Create a domain for container-to-host communication:

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

```

This configuration writes `/etc/resolver/host.container.internal` and enables containers to resolve `http://host.container.internal:8000` to reach a service running on the host.

## Container-to-Host DNS Resolution

When the `--localhost <ipv4>` flag is supplied to `container system dns create`, the specified IPv4 address becomes the A record for the domain. This mechanism, documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md), bridges the container network to the host.

The `DNSConfig` struct in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) stores the domain configuration, while the runtime ensures consistent application across container launches.

## Verifying DNS Configuration

Verify that macOS recognizes the resolver entry:

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

```

Expected output:

```

nameserver[0] : 203.0.113.113

```

List all configured DNS domains:

```bash
container system dns list

```

This displays all domains created via `container system dns create`, along with their associated localhost addresses.

## Summary

- **Per-container DNS** is configured via `--dns`, `--dns-search`, and related flags parsed in [`Flags.swift`](https://github.com/apple/container/blob/main/Flags.swift) and applied through [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift).
- **System-level DNS** is controlled through the `[dns]` section in `~/.config/container/config.toml`, decoded by [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift).
- **Host resolver integration** requires `sudo container system dns create`, which writes to `/etc/resolver/` and registers the domain with macOS.
- **Container-to-host bridging** uses the `--localhost` flag to create A records pointing to host services.
- **Verification** uses standard macOS tools like `scutil --dns` and `container system dns list`.

## Frequently Asked Questions

### How do I make a container reach a service running on my Mac host?

Use `sudo container system dns create <domain> --localhost <host-ip>` to create a DNS entry that resolves to your host's IP address within the container network. As documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md), this writes a resolver file to `/etc/resolver/` and allows containers to connect to host services using the configured domain.

### Where does the Container tool store its DNS configuration?

The tool stores system-level DNS configuration in `~/.config/container/config.toml`, which decodes into the `ContainerSystemConfig` struct in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift). Runtime per-container DNS settings are stored in `ContainerConfiguration.DNSConfiguration` within each container's runtime configuration.

### Can I use custom DNS servers for specific containers without affecting the system?

Yes. Pass `--dns <ip>` flags to `container run` or `container create`. 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 the container-specific `DNSConfiguration` object without modifying system-wide DNS settings.

### Why does `container system dns create` require sudo privileges?

The command requires `sudo` because it writes resolver files to `/etc/resolver/`, which is a protected system directory on macOS. This integration allows the macOS native resolver to forward queries for the specified domain to the container's virtual network.