numa/README.md

Numa

DNS you own. Everywhere you go.

Block ads and trackers. Override DNS for development. Cache for speed. A single portable binary built from scratch in Rust — no Raspberry Pi, no cloud, no account.

Why

• Ad blocking that travels with you — 385K+ domains blocked out of the box. Works on any network: coffee shops, hotels, airports.
• Developer overrides — point any hostname to any IP with auto-revert. No more editing /etc/hosts.
• Sub-millisecond caching — cached lookups in 0ms. Faster than any public resolver.
• Live dashboard — real-time query stats, blocking controls, override management at http://localhost:5380.
• Single binary, zero config — just run it.

Quick Start

cargo build
sudo cargo run                      # binds to port 53

Open the dashboard: http://localhost:5380

Test it:

dig @127.0.0.1 google.com           # normal resolution
dig @127.0.0.1 ads.google.com       # blocked → 0.0.0.0

Resolution Pipeline

Query → Overrides → Blocklist → Local Zones → Cache → Upstream → Respond

1. Overrides — ephemeral, time-scoped redirects (highest priority)
2. Blocklist — 385K+ ad/tracker domains → returns 0.0.0.0 / ::
3. Local zones — records defined in [[zones]] config
4. Cache — TTL-adjusted cached upstream responses (sub-ms)
5. Forward — query upstream resolver, cache the result
6. SERVFAIL — returned on upstream failure

Dashboard

Live at http://localhost:5380 when Numa is running:

• Total queries, cache hit rate, blocked count, uptime
• Resolution path breakdown (forward / cached / local / override / blocked)
• Scrolling query log with colored path tags
• Active overrides with create/edit/delete
• Blocking controls: toggle on/off, pause 5 minutes, one-click allowlist
• Cached domains list

Configuration

numa.toml (all sections optional, sensible defaults if missing):

[server]
bind_addr = "0.0.0.0:53"
api_port = 5380

[upstream]
address = "8.8.8.8"
port = 53
timeout_ms = 3000

[cache]
max_entries = 10000
min_ttl = 60
max_ttl = 86400

[blocking]
enabled = true
lists = [
  "https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/hosts/pro.txt",
]
refresh_hours = 24
allowlist = []

[[zones]]
domain = "mysite.local"
record_type = "A"
value = "127.0.0.1"
ttl = 60

HTTP API

REST API on port 5380 (18 endpoints):

Endpoint	Method	Description
/	GET	Live dashboard
/overrides	POST	Create override(s)
/overrides	GET	List active overrides
/overrides	DELETE	Clear all overrides
/overrides/environment	POST	Batch load overrides
/overrides/{domain}	GET	Get specific override
/overrides/{domain}	DELETE	Remove specific override
/blocking/stats	GET	Blocklist stats (domains loaded, sources, enabled)
/blocking/toggle	PUT	Enable/disable blocking
/blocking/pause	POST	Pause blocking for N minutes
/blocking/allowlist	GET	List allowlisted domains
/blocking/allowlist	POST	Add domain to allowlist
/blocking/allowlist/{domain}	DELETE	Remove from allowlist
/diagnose/{domain}	GET	Trace resolution path
/query-log	GET	Recent queries (filterable)
/stats	GET	Server statistics
/cache	GET	List cached entries
/cache	DELETE	Flush cache
/cache/{domain}	DELETE	Flush specific domain
/health	GET	Health check

How It Compares

	Pi-hole	NextDNS	Cloudflare	Numa
Ad blocking	Yes	Yes	Limited	385K+ domains
Portable	No (Raspberry Pi)	Cloud only	Cloud only	Single binary
Developer overrides	No	No	No	REST API + auto-expiry
Data stays local	Yes	Cloud	Cloud	100% local
Zero config	Complex setup	Yes	Yes	Works out of the box
Self-sovereign DNS	No	No	No	pkarr/DHT roadmap

Use Cases

Block ads everywhere — Run Numa on your laptop. Your ad blocker works on any network.

Mock external services — Point api.stripe.com to localhost:8080 for 30 minutes

Provision dev environments — Create overrides for db.dev, api.dev, cache.dev

Debug DNS — /diagnose/example.com traces the full resolution path

Docker

docker build -t numa .
docker run -p 53:53/udp -p 5380:5380 numa

Dependencies

tokio, axum, serde, serde_json, toml, log, env_logger, reqwest

Zero external DNS libraries. Wire protocol (RFC 1035) parsed from scratch.

License

MIT