DNS

CMDHub includes a built-in DNS responder so that custom local domains like myapp.test resolve to your machine without any manual /etc/hosts editing.

How it works

CMDHub runs a DNS server on port 15353 that answers queries for *.test (or whichever TLD you configure) with 127.0.0.1. macOS is then configured to send queries for that TLD to CMDHub’s resolver instead of your normal DNS server.

This means:

• Every *.test domain resolves to localhost automatically.
• No per-project /etc/hosts entries needed.
• Adding a new project’s domain works instantly - no DNS flush required.

macOS resolver setup

CMDHub creates a resolver file at /etc/resolver/test with contents like:

nameserver 127.0.0.1
port 15353

macOS reads files in /etc/resolver/ and routes DNS queries for matching TLDs to the specified nameserver. This is the same mechanism used by dnsmasq-based setups, but without needing dnsmasq.

Note

Creating /etc/resolver/test requires elevated privileges. CMDHub will prompt for your macOS password when setting up DNS for the first time, or when you change the TLD.

Configuring the TLD

The default TLD is .test. To change it:

1. Open CMDHub settings → DNS tab.
2. Enter a new TLD (without the leading dot), e.g. local or dev.
3. Click Apply. CMDHub removes the old resolver file and creates a new one.

Caution

.local is reserved by mDNS (Bonjour) on macOS. Avoid using it as your CMDHub TLD.

Multiple TLDs

You can add more than one TLD if you work across multiple environments or need to match an existing team convention. Each TLD gets its own entry in /etc/resolver/ and all of them resolve to 127.0.0.1.

Relationship to the reverse proxy

The DNS responder and the reverse proxy work together:

• DNS resolves the domain name to 127.0.0.1.
• Reverse proxy receives the request on port 80/443 and routes it to the correct service based on the subdomain.

If the proxy is disabled, DNS still resolves the domain - but nothing will be listening on ports 80/443 to handle the request.

Checking DNS resolution

To verify a domain is resolving correctly:

dig myapp.test @127.0.0.1 -p 15353

Or with the system resolver (after CMDHub has set up /etc/resolver/):

dns-sd -G v4 myapp.test

See Troubleshooting → DNS not resolving if domains are not resolving as expected.