# How to Configure DNS and Network Settings for Containers Managed by apple/container

> Learn to configure DNS and network settings for apple/container. Edit config.toml for defaults or use CLI flags like --dns-domain and --subnet for per-container overrides.

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

---

**You can configure DNS and network settings for apple/container by editing the [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file for persistent system-wide defaults or using CLI flags like `--dns-domain` and `--subnet` for per-container overrides.**

The apple/container repository stores global configuration in a TOML file parsed into the `ContainerSystemConfig` Swift model at runtime. By modifying the `DNSConfig` and `NetworkConfig` structs—defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift)—you control domain resolution, IP addressing, and container reachability from the macOS host.

## Understanding the Configuration Architecture

All top-level system configuration resides in [`config.toml`](https://github.com/apple/container/blob/main/config.toml), which the daemon decodes into the `ContainerSystemConfig` struct. This model contains two primary sub-configurations: **DNSConfig** for domain resolution and **NetworkConfig** for subnet allocation. Place this file at `$HOME/.container/config.toml` for user-specific settings or [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) for system-wide defaults.

## Configuring DNS Settings

DNS configuration controls how container hostnames resolve both inside containers and from the macOS host system.

### Setting the Default DNS Domain in config.toml

The `DNSConfig` struct contains an optional `domain: String?` property that appends a domain suffix to container hostnames. When configured, a container named `my-web-server` becomes reachable as `my-web-server.<domain>` from the host.

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

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

```

According to the source code in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), this value initializes the DNS domain for all containers launched without explicit runtime overrides.

### Overriding DNS at Runtime with CLI Flags

Override the default domain for individual containers using the `--dns-domain` flag (or `-d` shorthand) when executing `container run`. Specify custom DNS servers with the `--dns` flag:

```bash
container run \
  --dns 192.168.1.53 \
  --dns-domain dev \
  --name my-app \
  ubuntu:latest

```

This command populates the container's [`/etc/resolv.conf`](https://github.com/apple/container/blob/main//etc/resolv.conf) with the specified nameserver while registering `my-app.dev` as the resolvable hostname on the host.

### Managing Local DNS Domains with the CLI

The CLI provides commands to create host-side DNS resolver entries that map container names to IPs using macOS's resolver system. These operations write to `/etc/resolver/<domain>` and require sudo privileges.

Create a local DNS domain:

```bash
sudo container dns domain add test --ipv4 10.0.0.1

```

This command creates `/etc/resolver/test` containing `nameserver 10.0.0.1` and registers the domain with macOS via `scutil --dns`.

Remove a domain:

```bash
sudo container dns domain delete test

```

List all configured domains:

```bash
container dns domain list

```

## Configuring Network Settings

Network configuration defines the IP address ranges assigned to container networks, controlled by the `NetworkConfig` struct in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift).

### Defining Subnets in config.toml

The `NetworkConfig` struct accepts optional IPv4 and IPv6 CIDR strings through the `subnet` and `subnetv6` properties. When omitted, the daemon automatically allocates non-overlapping subnets.

Configure persistent subnets in [`config.toml`](https://github.com/apple/container/blob/main/config.toml):

```toml
[network]
subnet = "172.20.0.0/16"
subnetv6 = "fd00:dead:beef::/48"

```

### Specifying Subnets Per Container or Network

Override these defaults when creating networks using the `--subnet` and `--subnet-v6` flags:

```bash
container network create mynet \
  --subnet 172.20.0.0/16 \
  --subnet-v6 fd00:dead:beef::/48

```

If you omit these flags, the system selects free CIDR ranges automatically based on current network state.

## Practical Configuration Examples

### System-Wide Default Configuration

Create [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) with persistent DNS and network defaults:

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

[network]
subnet = "10.100.0.0/16"
subnetv6 = "fd00:10:100::/56"

```

These values apply to all containers and networks unless explicitly overridden at runtime.

### Ad-Hoc Container with Custom DNS

Launch a container with specific DNS overrides without modifying the config file:

```bash
container run \
  --dns 8.8.8.8 \
  --dns-domain staging \
  --name web-server \
  nginx:latest

```

### Creating a Local Resolver Entry

Enable hostname resolution for a development domain:

```bash
sudo container dns domain add localdev --ipv4 127.0.0.1
container run --dns-domain localdev --name api alpine:latest

```

The container is now reachable as `api.localdev` from the host.

## Summary

- **Configuration File**: Edit [`config.toml`](https://github.com/apple/container/blob/main/config.toml) (at `$HOME/.container/config.toml` or [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml)) to set persistent DNS domains and network subnets via the `ContainerSystemConfig` model.
- **DNS Domain**: Set the `domain` field in `[dns]` section for TOML-based configuration, or use `--dns-domain` and `--dns` flags for per-container overrides.
- **Network Subnets**: Define `subnet` and `subnetv6` in the `[network]` section, or specify `--subnet` and `--subnet-v6` when creating networks.
- **Local Resolution**: Use `container dns domain add|delete|list` commands to manage macOS resolver entries in `/etc/resolver/`, enabling system-wide hostname resolution for container domains.
- **Source Reference**: All configuration structures are implemented in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) and documented in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md) and [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md).

## Frequently Asked Questions

### Where does apple/container store its configuration file?

The system searches for [`config.toml`](https://github.com/apple/container/blob/main/config.toml) in `$HOME/.container/config.toml` for user-specific settings or [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) for system-wide defaults. This file maps directly to the `ContainerSystemConfig` struct defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), which contains the `DNSConfig` and `NetworkConfig` sub-models.

### How do I make containers reachable by hostname from my Mac?

Use the `container dns domain add` command to register a local DNS resolver. Executing `sudo container dns domain add test --ipv4 10.0.0.1` creates a file at `/etc/resolver/test` and registers the domain with macOS, allowing resolution of `<container-name>.test` addresses from the host system.

### Can I configure different DNS servers for individual containers?

Yes. While the `[dns]` section in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) sets system-wide defaults, you can override DNS settings per container using the `--dns` flag to specify nameserver IP addresses and `--dns-domain` to set the search domain when running `container run`. These runtime flags map directly to properties in the `DNSConfig` struct.

### What happens if I don't specify a network subnet?

If you omit the `subnet` and `subnetv6` fields from [`config.toml`](https://github.com/apple/container/blob/main/config.toml) or omit `--subnet` flags when creating networks, the apple/container daemon automatically allocates non-overlapping IPv4 and IPv6 CIDR ranges. This automatic allocation is handled by the initialization logic in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) to prevent address conflicts.