Local DNS names

On apple/container, Gantry can make every container reachable by name — name.domain — across your whole Mac, OrbStack-style. This page explains how it works and how to set it up.

How it works

apple/container ships a local DNS server (on 127.0.0.1:2053). When you create a local domain, macOS is told to route that domain's lookups to it (via a file in /etc/resolver). A container started under that domain then resolves as <name>.<domain> to its routable IP.

Two things are required for names to resolve from the host:

  1. The domain must exist (container system dns create <domain>).
  2. It must be the default DNS domain, set in ~/.config/container/config.toml, and the services restarted.

Gantry does both for you.

Set it up in Gantry

  1. Open Settings → Apple.
  2. Under Local DNS Domains, add a domain (for example test). Creating a domain needs administrator approval — macOS will prompt once. The first domain you add becomes the default automatically.
  3. Click the star to mark a domain as the default. Gantry writes it into apple/container's config and shows a Restart Services button — click it.

From now on, containers you create in Gantry are assigned the default domain automatically, with a unique name derived from the image (e.g. nginx, then nginx-2). They resolve immediately — Gantry flushes the DNS cache for you.

Tip
You can also set the domain per container in New Container and Quick Run, under Networking.

Naming an existing container

A container's DNS domain is fixed when it's created, so apple/container can't change it on a running container. In the container's Overview → Address section, use Assign / Change DNS Name… — Gantry recreates the container with the new domain, preserving its image, command, environment, published ports, volume binds, restart policy and labels. Named volumes and bind mounts are kept; only the container's writable layer is reset (exactly like docker rm + docker run).

Doing it by hand

If you prefer the CLI:

Terminal
# 1. create the domain (asks for admin)
sudo container system dns create test

# 2. make it the default domain
mkdir -p ~/.config/container
printf '[dns]\ndomain = "test"\n' > ~/.config/container/config.toml

# 3. restart services, then run a container
container system stop && container system start
container run -d --name web docker.io/library/nginx:alpine

# 4. resolve it
dscacheutil -flushcache
curl http://web.test/

Caveats

  • Only containers created after the default domain is set are registered — recreate older ones (Gantry's Assign DNS Name does this).
  • macOS caches negative lookups: if you tried a name before it existed, flush with dscacheutil -flushcache. Gantry flushes automatically after a recreate or services restart.
  • The container's IP always works even when a name doesn't — Gantry's open-in-browser uses the IP for reliability.