# How to Configure DNS Domains for Host Connections in Apple Container

> Configure DNS domains for host connections in Apple Container easily. Use container system dns commands and flags for flexible setup. Learn how to manage your container network.

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

---

**Use the `container system dns` command to register a domain with macOS, set a system-wide default in [`config.toml`](https://github.com/apple/container/blob/main/config.toml), or override per-container with the `--dns-domain` flag.**

The `apple/container` repository provides an embedded DNS service that bridges container networking to the macOS host. Configuring DNS domains for host connections enables hostname resolution from the host to containers using custom suffixes rather than IP addresses. This integration works through three distinct layers: system-wide configuration, CLI-managed resolver files, and per-container runtime flags.

## System-Wide DNS Configuration

The global DNS behavior is defined in the top-level [`config.toml`](https://github.com/apple/container/blob/main/config.toml) under the `[dns]` section. The `domain` key supplies a suffix that is automatically appended to every container name, creating fully qualified domain names resolvable from the host.

### The DNSConfig Implementation

According to the source code in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), the `DNSConfig` class (lines 34-41) defines the structure for system-wide DNS settings. This configuration persists across container restarts and applies to all containers unless explicitly overridden.

### Configuring the Domain Suffix

Add the following to your [`config.toml`](https://github.com/apple/container/blob/main/config.toml):

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

```

With this setting, a container started with `--name my-web-server` becomes reachable as `my-web-server.test` from the macOS host. The embedded DNS server automatically resolves this name to the container's virtual IP address.

## Managing DNS Domains via CLI

On macOS, the tool creates resolver files under `/etc/resolver/` and reloads the system DNS cache. This bridges the gap between the container runtime and the host's resolver subsystem.

### Creating a DNS Domain

Use the `system dns` subcommand to register a new domain:

```bash
sudo container system dns create test

```

This writes a file at `/etc/resolver/test` and triggers a DNS reload, as documented in [`docs/tutorials/start-here.md`](https://github.com/apple/container/blob/main/docs/tutorials/start-here.md) (lines 8-14). Verify the configuration using:

```bash
scutil --dns | grep 'domain : test'

```

### Removing a DNS Domain

To unregister a domain and remove its resolver file:

```bash
sudo container system dns delete test

```

## Per-Container DNS Overrides

Individual containers can override the system-wide domain or specify their own using runtime flags.

### Using the --dns-domain Flag

As implemented in [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) (lines 19-40), the `--dns-domain` option allows per-container customization:

```bash
container run --name db --dns-domain custom.local my-db-image

```

The host can now reach this container at `db.custom.local`, regardless of the system default.

### Validation Rules

The source code validates that `--no-dns` cannot be combined with DNS-related flags. The `validate()` method ensures mutual exclusivity between disabling DNS and specifying custom domains, preventing configuration conflicts.

## Complete Configuration Example

Combine these layers to set up a working DNS resolution workflow:

```bash

# 1. Create a local DNS domain called "test"

sudo container system dns create test

# 2. Run a container with automatic hostname suffixing

container run --name my-web-server --detach --rm \
    --publish 8080:80 \
    my-image

# 3. Verify resolution from the host

ping my-web-server.test

# 4. Run a container with a custom domain override

container run --name db --dns-domain custom.local my-db-image

# 5. Access the overridden container

ping db.custom.local

```

When the system domain is `test` and you launch a container named `my-web-server`, the embedded DNS server appends the suffix and resolves `my-web-server.test` to the container's virtual IP (typically in the `192.168.64.x` range).

## Summary

- **System configuration**: Define a default domain in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) under the `[dns]` section, implemented in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift).
- **CLI management**: Use `sudo container system dns create <domain>` to write resolver files to `/etc/resolver/` and register domains with macOS.
- **Per-container overrides**: Specify `--dns-domain` for individual containers, validated in [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift).
- **Resolution flow**: The host's resolver sees the custom domain, the runtime appends the suffix, and the embedded DNS server maps hostnames to virtual IPs.

## Frequently Asked Questions

### How do I verify that my DNS domain is active on macOS?

Check the resolver configuration using `scutil --dns` and grep for your domain name. You should see an entry pointing to the container's DNS server. If the domain is missing, ensure you ran `sudo container system dns create` with administrative privileges.

### Can I use multiple DNS domains simultaneously?

Yes. You can create multiple resolver files using `container system dns create` for different domains, and containers can use different domains via the `--dns-domain` flag. However, each container can only have one domain suffix applied to its hostname at runtime.

### What happens if I specify `--dns-domain` but the system config has a different domain?

The `--dns-domain` flag overrides the system-wide setting from [`config.toml`](https://github.com/apple/container/blob/main/config.toml) for that specific container. The per-container flag takes precedence, allowing you to mix containers with different domain suffixes on the same host.

### Where does the container tool store DNS configuration on macOS?

The system domain is stored in the user's [`config.toml`](https://github.com/apple/container/blob/main/config.toml). Runtime domains are registered in `/etc/resolver/<domain>` files managed by the CLI commands. The `DNSConfig` struct in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) defines the in-memory representation of these settings.