dns-config

name

dns-config

description

Manage the local-dns-override hosts.yaml configuration file. Use when you need to view the current DNS config, validate a hosts.yaml file before applying it, understand the config file format, or check which records are currently loaded. Triggers include "show DNS config", "validate hosts.yaml", "check loaded records", "DNS config file", "list local DNS entries", or any task involving viewing or validating the DNS record configuration.

dns-config

View and validate the local-dns-override hosts.yaml configuration.

When to use

• Checking what records are currently loaded
• Validating a new hosts.yaml before saving it
• Understanding the full config file format
• Debugging why a hostname is not resolving as expected

hosts.yaml full format reference

# Optional: override the upstream DNS resolver
# Format: host:port
# Default: 8.8.8.8:53
upstream: 8.8.8.8:53

records:
  - hostname: api.local        # required: non-empty string
    type: A                    # required: A | AAAA | CNAME
    value: 127.0.0.1           # required: IPv4 / IPv6 / hostname
    ttl: 60                    # optional: seconds, default 60

  - hostname: "*.dev.local"    # wildcard: quote the string in YAML
    type: A
    value: 127.0.0.1

  - hostname: www.api.local
    type: CNAME
    value: api.local           # CNAME value must be a valid hostname

Show current loaded config via CLI

node dist/dns-server.js config
node dist/dns-server.js config --config /path/to/hosts.yaml

Show config via API

# Full config object
curl -s http://127.0.0.1:5380/api/config | jq .

# Just the records array
curl -s http://127.0.0.1:5380/api/config | jq '.records'

# Count of records
curl -s http://127.0.0.1:5380/api/config | jq '.records | length'

# Find all wildcard records
curl -s http://127.0.0.1:5380/api/config | jq '[.records[] | select(.hostname | startswith("*"))]'

Validate before applying

# Dry-run validation (exit 0 = valid, exit 1 = errors printed)
node dist/dns-server.js config --validate-only --config ./hosts.yaml

Config API response shape

{
  "upstream": "8.8.8.8:53",
  "configPath": "./hosts.yaml",
  "loadedAt": "2026-03-20T15:53:10Z",
  "records": [
    {
      "hostname": "api.local",
      "type": "A",
      "value": "127.0.0.1",
      "ttl": 60,
      "wildcard": false
    },
    {
      "hostname": "*.dev.local",
      "type": "A",
      "value": "127.0.0.1",
      "ttl": 60,
      "wildcard": 
    
  

Environment variables that affect config loading

Variable	Effect
DNS_CONFIG	Path to hosts.yaml (default: ./hosts.yaml)
UPSTREAM_DNS	Override upstream field in YAML

Common validation errors

Error message	Fix
record[N].value: not a valid IPv4	Check IPv4 format - must be 4 octets 0-255
record[N].hostname: empty	hostname field is required and non-empty
record[N].type: unknown	type must be exactly A, AAAA, or CNAME
upstream: invalid format	upstream must be host:port format
path traversal detected	config path must not escape the project root