Records, wildcards, runtime management, upstream fallback.
Records live at ~/.phind/records.json. Wildcards, multiple domains, cross-host targets — all part of the same naming layer.
export PHIND_STORAGE_PATH=/your/path
phind requires a restart to pick up direct file changes. Use the HTTP API to manage records at runtime — cache clears automatically.
Unknown names fall through to upstream DNS. Results are cached in memory. Both transports on port 8053.
TCP handles automatic client fallback when UDP responses are truncated — important for DNSSEC, large TXT records, and SPF chains if routing real network traffic through phind.
CNAME chain exampleapi.phind is a CNAME pointing to auth.phind, which has an A record. phind follows the chain and returns the final address.
$ dig @127.0.0.1 -p 8053 api.dev
phind listens on port 8053 and won't affect normal DNS until you point something at it.
# Point your router's DNS at the machine running phind.
# All devices on the network get local domain resolution,
# everything else falls through upstream as usual.
DNS Server: 192.168.1.x
If the machine running phind goes down, your network loses DNS until it comes back.
# /etc/dnsmasq.conf
server=/.phind/127.0.0.1#8053
server=/.dev/127.0.0.1#8053
Forwards only your dev domains to phind. Everything else is unaffected.
$ dig @127.0.0.1 -p 8053 app.phind
No config needed. .phind domains won't work in your browser without one of the other options.
A separate service for managing records, querying resolution, and streaming live metrics.
$ bin/phind-http http://127.0.0.1:8080
| method | endpoint | description |
|---|---|---|
| GET | /records | list all |
| POST | /records | add or update |
| DELETE | /records/{hostname} | remove |
| GET | /resolve | resolve a name |
| GET | /metrics | snapshot |
| GET | /events | SSE stream |
| GET | /status | server status |
| POST | /cache/clear | flush cache |
Tracks cache hits/misses, latency, local vs. upstream resolution, upstream forwards, and failures. Metrics stay in memory — writes are never in the lookup path.
$ curl -N http://127.0.0.1:8080/events
export PHIND_OTLP_ENDPOINT=\
http://localhost:4318/phind/events
event: metrics · 1s interval
{
"queries_today": 142,
"cache_hits": 118,
"cache_misses": 24,
"cache_hit_rate": 0.83,
"upstream_forwards": 19,
"resolution_failures": 0,
"recent_queries": [...],
"logs": [...]
}