# How to Configure DNS and Network Settings for Containers in apple/container > Learn to configure DNS and network settings for apple/container managed containers. Use TOML files or CLI flags for easy setup and control. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-11 --- **You configure DNS and network settings for containers managed by apple/container through a TOML configuration file at `~/.container/config.toml` or [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml), with optional runtime overrides via the `--dns-domain`, `--subnet`, and `--subnet-v6` CLI flags.** The **apple/container** repository provides a Swift-based container runtime that centralizes system configuration in a single `ContainerSystemConfig` model. This architecture allows you to define persistent DNS domains and network subnets globally while retaining the flexibility to override them per container at launch time. ## Configuration File Structure All top-level settings are stored in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) and parsed into the `ContainerSystemConfig` Swift struct defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift). The file uses standard TOML syntax with dedicated sections for DNS and network parameters. ### DNS Configuration (DNSConfig) The **DNSConfig** struct contains a single optional field `domain: String?` that controls the default DNS domain appended to container hostnames. When `domain` is set, containers become reachable as `.` from the host. If the field is `nil`, no domain suffix is added. **Global configuration in [`config.toml`](https://github.com/apple/container/blob/main/config.toml):** ```toml [dns] domain = "test" ``` This setting persists across all containers unless overridden at runtime. The `ContainerSystemConfig` initializer reads this value from the TOML `[dns]` section and stores it in the `DNSConfig.domain` property. ### Network Configuration (NetworkConfig) The **NetworkConfig** struct manages IP addressing through two optional CIDR string fields: `subnet` (IPv4) and `subnetv6` (IPv6). When omitted, the daemon automatically allocates non-overlapping subnets. Explicitly defining these prevents automatic allocation and ensures consistent addressing across container restarts. **Global configuration 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" ``` These values map directly to `NetworkConfig.subnet` and `NetworkConfig.subnetv6` in the Swift source, as implemented in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift). ## Runtime CLI Overrides The `container run` and `container network create` commands accept flags that override [`config.toml`](https://github.com/apple/container/blob/main/config.toml) settings for specific containers or networks. ### DNS Flags Use the `--dns-domain` (or `-d`) flag to specify a domain suffix at runtime: ```bash container run --dns-domain dev --name my-app ubuntu:latest ``` This makes the container reachable as `my-app.dev` from the host, regardless of the global [`config.toml`](https://github.com/apple/container/blob/main/config.toml) setting. The flag updates the `DNSConfig` domain property for this specific container instance. ### Network Flags Specify custom subnets when creating networks: ```bash container network create mynet \ --subnet 172.30.0.0/16 \ --subnet-v6 fd00:cafe::/48 ``` These flags populate the `NetworkConfig` fields at creation time, bypassing automatic subnet allocation. ## Managing Local DNS Domains The container daemon can create host-side DNS resolvers that map container names to their IPs using macOS's resolver system. This requires writing to `/etc/resolver/` and registering with `scutil`. ### Adding DNS Domains Create a local DNS domain that resolves container names to specific IPs: ```bash sudo container dns domain add test --ipv4 10.0.0.1 ``` This command performs two operations: 1. Writes a resolver file to `/etc/resolver/test` containing `nameserver 10.0.0.1` 2. Registers the domain with the macOS resolver via `scutil --dns` ### Listing and Removing Domains View all configured domains: ```bash container dns domain list ``` **Example output:** ``` test 10.0.0.1 dev 192.168.1.53 ``` Remove a domain and its resolver configuration: ```bash sudo container dns domain delete test ``` This deletes the file at `/etc/resolver/test` and updates the system resolver configuration. ## Complete Configuration Examples ### Global config.toml Setup Create a system-wide configuration that applies to all containers: ```toml # ~/.container/config.toml or /etc/container/config.toml [dns] domain = "internal" [network] subnet = "10.0.0.0/16" subnetv6 = "fd00::/48" ``` With this configuration, every container launched without explicit flags receives the `internal` domain suffix and operates within the `10.0.0.0/16` subnet. ### Per-Container Overrides Launch a container with custom DNS and network settings: ```bash container run \ --dns 192.168.1.53 \ --dns-domain dev \ --subnet 172.20.0.0/24 \ --name web-server \ nginx:latest ``` This container: - Uses `192.168.1.53` as its DNS server (written to [`/etc/resolv.conf`](https://github.com/apple/container/blob/main//etc/resolv.conf) inside the container) - Is reachable as `web-server.dev` from the host - Operates on the `172.20.0.0/24` network segment ## Summary - **Configuration location**: Edit `~/.container/config.toml` or [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) to set system-wide defaults. - **DNS domain**: Set `[dns] domain` in TOML or use `--dns-domain` at runtime to append domain suffixes to container hostnames. - **Network subnets**: Define `[network] subnet` and `subnetv6` in TOML or use `--subnet` and `--subnet-v6` flags to control IP addressing. - **Local resolver**: Use `sudo container dns domain add --ipv4 ` to create host-side DNS entries in `/etc/resolver/`. - **Source files**: [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) defines the `DNSConfig` and `NetworkConfig` structs that parse these settings. ## Frequently Asked Questions ### Where does apple/container store its configuration files? The runtime searches for [`config.toml`](https://github.com/apple/container/blob/main/config.toml) in two locations: `$HOME/.container/config.toml` for user-specific settings and [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) for system-wide configuration. Values in the user home directory override system defaults. Both files are parsed into the `ContainerSystemConfig` Swift model at daemon startup. ### How do I make containers reachable by hostname from the macOS host? Create a local DNS domain using `sudo container dns domain add --ipv4 `. This writes a resolver file to `/etc/resolver/` and registers the domain with macOS via `scutil`. Combined with the `--dns-domain` flag when running containers, this enables hostname resolution like `my-container.test` from the host. ### What happens if I don't specify a subnet in config.toml? If `NetworkConfig.subnet` or `subnetv6` are nil in the configuration file, the apple/container daemon automatically allocates a non-overlapping subnet from the private address space. This automatic allocation occurs in the Swift runtime when the network configuration is initialized without explicit CIDR values. ### Can I use different DNS settings for each container? Yes. While the `[dns] domain` setting in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) provides a global default, you can override it per container using the `--dns-domain ` flag with `container run`. Additionally, use `--dns ` to specify custom DNS servers for individual containers, which populate [`/etc/resolv.conf`](https://github.com/apple/container/blob/main//etc/resolv.conf) inside the container filesystem.