# How to Configure Custom DNS Domains for Containers on macOS

> Learn to configure custom DNS domains for containers on macOS. Edit your config.toml and register your resolver with the container command for seamless integration.

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

---

**To configure custom DNS domains for containers on macOS, set the `domain` key in the `[dns]` section of `~/.config/container/config.toml`, then run `sudo container dns create <domain>` to register the resolver with macOS.**

The `apple/container` repository includes an embedded DNS server that automatically resolves container hostnames on the Mac host. By default, containers are reachable via their names, but you can configure a custom DNS domain—such as `myapp.test`—to access containers using fully qualified hostnames like `web.myapp`. This requires updating the Container system configuration and integrating with macOS's resolver infrastructure.

## Setting the DNS Domain in the Configuration File

The Container system reads its DNS settings from a TOML configuration file that defines the default domain appended to every container name. This file is parsed by `ContainerSystemConfig` (located in [[`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift)](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift)).

Create or edit the configuration file at `$HOME/.config/container/config.toml` to include the `[dns]` section:

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

```

With this setting, a container named `web` automatically becomes resolvable as `web.myapp`. If the configuration file does not exist, `container` creates one with defaults on first run.

## Registering the Domain with the macOS Resolver

Once the domain is configured, you must register it with macOS so the system resolver knows to query the Container DNS server. The `container` CLI provides a system command that writes the required resolver file under `/etc/resolver/` and reloads the system resolver configuration.

Run the following command to create the resolver entry:

```bash
sudo container dns create myapp

```

This command performs two critical actions: it writes a resolver file containing the address of the internal DNS server (by default `127.0.0.1:53`) to `/etc/resolver/myapp`, then signals `mDNSResponder` with `kill -HUP` to pick up the change. The implementation of this system-level integration lives in [[`Sources/ContainerCommands/System/SystemStart.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/System/SystemStart.swift)](https://github.com/apple/container/blob/main/Sources/ContainerCommands/System/SystemStart.swift).

## Verifying and Managing DNS Domains

After configuration, verify that the domain is active and resolving correctly:

```bash

# List all registered container DNS domains

container dns list

# Test resolution of a specific container

ping web.myapp

```

The `container dns list` command queries the same configuration state managed by `ContainerSystemConfig`, ensuring the domain matches what you set in the TOML file.

To remove a custom domain and stop resolution, delete the resolver entry:

```bash
sudo container dns delete myapp

```

This removes the `/etc/resolver/myapp` file and reloads the macOS resolver.

## Complete Configuration Walkthrough

The following commands demonstrate the full workflow from configuration to verification:

```bash

# 1. Create the configuration directory and set the DNS domain

mkdir -p $HOME/.config/container
cat > $HOME/.config/container/config.toml <<EOF
[dns]
domain = "myapp"
EOF

# 2. Register the domain with macOS (requires sudo for /etc/resolver/)

sudo container dns create myapp

# 3. Launch a container and test hostname resolution

container run --name web -d nginx
ping web.myapp

```

When the daemon starts, it loads the configuration from `ContainerSystemConfig` and passes the DNS settings to the embedded DNS service, which binds to `127.0.0.1:53` by default.

## Summary

- **Configure the domain** by setting the `domain` key in the `[dns]` section of `$HOME/.config/container/config.toml`, parsed by [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift).
- **Register with macOS** using `sudo container dns create <domain>` to write to `/etc/resolver/` and signal `mDNSResponder`.
- **Verify resolution** with `container dns list` and standard tools like `ping` to confirm containers resolve as `<name>.<domain>`.
- **Remove domains** using `sudo container dns delete <domain>` to clean up resolver entries.

## Frequently Asked Questions

### Where does the container system store its DNS configuration?

The DNS configuration is stored in `$HOME/.config/container/config.toml` under the `[dns]` table. The `ContainerSystemConfig` struct in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) decodes this file at startup, reading the `domain` key to determine the default DNS suffix for all containers.

### Why does creating a DNS domain require sudo privileges?

The `container dns create` command requires sudo because it writes to the `/etc/resolver/` directory, which is protected by macOS system permissions. This directory controls macOS DNS resolution behavior, and modifying it requires administrative access to ensure system security.

### How does the container DNS server integrate with macOS system resolution?

The Container DNS server runs on `127.0.0.1:53` and integrates with macOS by placing a resolver file in `/etc/resolver/` that points to this address. The CLI then sends a `SIGHUP` signal to `mDNSResponder` to reload the resolver configuration without requiring a system reboot, as implemented in the system command handlers.

### Can I use multiple custom DNS domains simultaneously?

While the [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file supports only one default `domain` value in the `[dns]` section, you can create multiple resolver entries by running `sudo container dns create <domain>` for different domains. However, all containers will share the single domain specified in the configuration file unless you manually manage resolver files for advanced use cases.