# How to Set Up Local DNS Domains for Containers Using `container system dns` Commands

> Easily set up local DNS domains for containers with apple/container system dns commands. Configure persistent DNS for all your containers and simplify domain resolution.

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

---

**The `container` CLI provides built-in `system dns` subcommands to create, list, and delete persistent DNS domains that are automatically resolved inside every container via the system configuration file.**

The `container` tool from the Apple container repository includes a native DNS configuration service that eliminates the need for manual resolver configuration. By using the `container system dns` commands, you can define custom domains in the system configuration file that propagate automatically to all containers. This article explains how to manipulate these DNS settings using the CLI and how the runtime applies them based on the source code in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) and [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift).

## Understanding the DNS Architecture

The DNS system in `container` consists of three primary components that work together to provide persistent, system-wide resolution.

### System Configuration Storage

All DNS domains are stored in the [`container-system-config.toml`](https://github.com/apple/container/blob/main/container-system-config.toml) file under the `[dns]` section. This configuration defines the default DNS domain, nameservers, search domains, and resolver options. According to the repository documentation in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md), this file serves as the single source of truth for DNS settings across the container runtime.

### Runtime DNS Injection

When a container starts, the runtime service reads the system configuration and injects the DNS settings into the container's [`resolv.conf`](https://github.com/apple/container/blob/main/resolv.conf). The implementation in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) handles this injection automatically. If the nameserver list is empty, the code falls back to the host's resolver (lines 218-224).

### CLI Flag Processing

The command-line interface validates DNS-related flags in [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift). This parser prevents contradictory usage of `--no-dns` alongside other DNS flags and merges user-provided settings with the system configuration via helper functions in [`Sources/Services/ContainerAPIService/Client/Utility.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Utility.swift).

## Creating Local DNS Domains

Use the `container system dns create` command to register a new domain that resolves within all containers.

The command accepts a domain name and an optional `--localhost` IP address (defaulting to `127.0.0.1`). When executed, it updates the `[dns]` section of [`container-system-config.toml`](https://github.com/apple/container/blob/main/container-system-config.toml) and restarts the DNS resolver service.

```bash

# Create a domain resolving to the default localhost

sudo container system dns create myapp.local

# Bind to a specific IP address

sudo container system dns create myapp.local --localhost 203.0.113.113

```

After creation, the domain becomes instantly resolvable from all containers as `myapp.local.` (the resolver automatically appends the trailing dot).

## Listing and Deleting DNS Domains

Manage existing domains using the `list` and `delete` subcommands.

### Listing Configured Domains

The `list` (or `ls`) command displays all custom domains and their associated localhost IPs:

```bash
container system dns list

```

Typical output:

```

DOMAIN           LOCALHOST
myapp.local      127.0.0.1
dev.test         203.0.113.113

```

### Removing Domains

The `delete` (or `rm`) command removes entries from the system configuration:

```bash
sudo container system dns delete myapp.local

```

Once deleted, containers can no longer resolve the domain.

## Per-Container DNS Overrides

While system DNS provides global defaults, you can override settings for individual containers using flags with `container run`.

These flags supplement or override the system-wide configuration:

```bash
container run \
    --dns 1.1.1.1 \
    --dns-domain example.com \
    --dns-search corp.example.com \
    --dns-option ndots:2 \
    myimage:latest

```

To disable DNS entirely for a specific container:

```bash
container run --no-dns myimage:latest

```

**Important:** The validation logic in [`Flags.swift`](https://github.com/apple/container/blob/main/Flags.swift) (lines 351-359) aborts execution if you combine `--no-dns` with any other DNS-related flags.

## Edge Cases and Validation Rules

Understanding these constraints prevents configuration errors.

- **Flag Conflicts**: Using `--no-dns` with `--dns`, `--dns-domain`, `--dns-search`, or `--dns-option` triggers a CLI error. Use either `--no-dns` or DNS flags, never both.
- **Empty Nameserver Fallback**: If you clear all nameservers in the configuration, [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) (lines 218-224) automatically falls back to the host's resolver.
- **Domain Collisions**: Creating a domain that already exists overwrites the previous entry. Always verify existing domains with `container system dns list` before creating new ones.
- **Non-Local IP Risks**: Specifying a non-local IP with `--localhost` breaks DNS queries inside containers. Keep the IP within the container's network range, typically `127.0.0.1` or the VM's loopback address.

## Summary

- The `container system dns` command manages persistent DNS domains in [`container-system-config.toml`](https://github.com/apple/container/blob/main/container-system-config.toml).
- The `create`, `list`, and `delete` subcommands provide full CRUD operations for local DNS domains.
- Runtime injection in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) automatically propagates DNS settings to every container's [`resolv.conf`](https://github.com/apple/container/blob/main/resolv.conf).
- The CLI validates flag combinations in [`Flags.swift`](https://github.com/apple/container/blob/main/Flags.swift), preventing `--no-dns` conflicts.
- Per-container overrides using `--dns*` flags merge with system defaults via [`Utility.swift`](https://github.com/apple/container/blob/main/Utility.swift).

## Frequently Asked Questions

### Where are DNS domains stored in the container system?

DNS domains are stored in the [`container-system-config.toml`](https://github.com/apple/container/blob/main/container-system-config.toml) file under the `[dns]` section. This file persists across daemon restarts and applies globally to all containers managed by the `container` tool.

### Can I use `--no-dns` with other DNS flags?

No. The CLI parser in [`Flags.swift`](https://github.com/apple/container/blob/main/Flags.swift) explicitly forbids combining `--no-dns` with any `--dns`, `--dns-domain`, `--dns-search`, or `--dns-option` flags. You must choose between disabling DNS entirely or configuring specific DNS settings.

### What happens if I don't specify a nameserver in the system config?

If the nameserver list is empty, the runtime code in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) (lines 218-224) automatically falls back to using the host system's resolver. However, explicitly setting at least one nameserver is recommended for predictable behavior.

### Do DNS changes require restarting containers?

No. When you use `container system dns create` or `delete`, the command restarts the DNS resolver service automatically. New containers pick up these changes immediately, though running containers may need to be restarted to see updates depending on how they cache DNS configuration.