local-dns

name

local-dns

description

Add or remove local hostname-to-IP mappings using local-dns-override. Use when you need to resolve a custom hostname (like api.local or *.dev.local) to a local IP address for development, check what a hostname currently resolves to, or test that a DNS record is working. Triggers include "add DNS record", "map hostname to IP", "resolve api.local", "local hostname", "DNS override", or any task that involves making a custom domain point to 127.0.0.1 or another local address.

local-dns

Add hostname-to-IP mappings for development environments.

When to use

• Making api.local resolve to 127.0.0.1 so local services respond to readable names
• Adding a wildcard *.dev.local that catches any subdomain
• Testing that a hostname resolves correctly through the local DNS server
• Looking up what IP a configured hostname returns

Add a record via hosts.yaml

Edit hosts.yaml and add to the records array:

records:
  # A record - maps hostname to IPv4
  - hostname: api.local
    type: A
    value: 127.0.0.1

  # Wildcard - matches any subdomain of dev.local
  - hostname: "*.dev.local"
    type: A
    value: 127.0.0.1

  # CNAME - alias one hostname to another
  - hostname: www.api.local
    type: CNAME
    value: api.local

  # AAAA record - maps hostname to IPv6
  - hostname: api.local
    type: AAAA
    value: ::1

  # Custom TTL (default is 60 seconds)
  - hostname: cache.local
    type: A
    value: 10.0.0.5
    ttl: 300

The server hot-reloads on file change - no restart needed.

Trigger a manual reload via API

curl -s -X POST http://127.0.0.1:5380/api/reload
# Response: { "ok": true, "records": 9, "reloadedAt": "2026-03-20T15:53:10Z" }

Test a hostname via CLI

# Test A record
node dist/dns-server.js test api.local

# Test CNAME resolution
node dist/dns-server.js test www.api.local --type CNAME

# Test using dig (port 5353 if not running on 53)
dig @127.0.0.1 -p 5353 api.local A
dig @127.0.0.1 -p 5353 api.local AAAA
dig @127.0.0.1 -p 5353 www.api.local CNAME

View current records via API

curl -s http://127.0.0.1:5380/api/config | jq '.records'

Supported record types

Type	Value	Use case
A	IPv4 (1.2.3.4)	Map hostname to IPv4
AAAA	IPv6 (::1)	Map hostname to IPv6
CNAME	Hostname target	Alias one hostname to another

Wildcard matching rules

• Only *.prefix.local form is supported
• A wildcard matches exactly one subdomain level: *.dev.local matches foo.dev.local but not a.b.dev.local
• Exact matches take priority over wildcards

Troubleshooting

Hostname still not resolving

Check that 127.0.0.1 (or 127.0.0.1:5353) is set as your system DNS resolver. The local-dns-override server must be the first resolver consulted.

Record added but not resolving

1. Check that the server reloaded: curl http://127.0.0.1:5380/api/config
2. Check the query log for NXDOMAIN: curl http://127.0.0.1:5380/api/log?limit=10
3. Verify YAML syntax is valid: node dist/dns-server.js config