numa 0.1.0

Ephemeral DNS overrides for development and testing. Point any hostname to any endpoint. Auto-revert when you're done.
Documentation

Numa

DNS you own. Everywhere you go.

A portable DNS resolver in a single binary. Block ads on any network, name your local services (frontend.numa), and override any hostname with auto-revert — all from your laptop, no cloud account or Raspberry Pi required.

Built from scratch in Rust. Zero DNS libraries. RFC 1035 wire protocol parsed by hand.

Numa dashboard

Quick Start

# Install
curl -fsSL https://raw.githubusercontent.com/razvandimescu/numa/main/install.sh | sh

# Run (port 53 requires root)
sudo numa

# Try it
dig @127.0.0.1 google.com           # ✓ resolves normally
dig @127.0.0.1 ads.google.com       # ✗ blocked → 0.0.0.0

Open the dashboard: http://numa.numa (or http://localhost:5380)

Or build from source:

git clone https://github.com/razvandimescu/numa.git && cd numa
cargo build --release
sudo ./target/release/numa

Why Numa

  • Ad blocking that travels with you — 385K+ domains blocked via Hagezi Pro. Works on any network: coffee shops, hotels, airports.
  • Local service proxy — https://frontend.numa instead of localhost:5173. Auto-generated TLS certs, WebSocket support for HMR. Like /etc/hosts but with a dashboard and auto-revert.
  • Developer overrides — point any hostname to any IP, auto-reverts after N minutes. REST API with 22 endpoints.
  • Sub-millisecond caching — cached lookups in 0ms. Faster than any public resolver.
  • Live dashboard — real-time stats, query log, blocking controls, service management.
  • macOS + Linux — numa install configures system DNS, numa service start runs as launchd/systemd service.

Local Service Proxy

Name your local dev services with .numa domains:

curl -X POST localhost:5380/services \
  -H 'Content-Type: application/json' \
  -d '{"name":"frontend","target_port":5173}'

open http://frontend.numa            # → proxied to localhost:5173
  • HTTPS with green lock — auto-generated local CA + per-service TLS certs
  • WebSocket — Vite/webpack HMR works through the proxy
  • Health checks — dashboard shows green/red status per service
  • Persistent — services survive restarts
  • Or configure in numa.toml:
[[services]]
name = "frontend"
target_port = 5173

How It Compares

Pi-hole AdGuard Home NextDNS Cloudflare Numa
Ad blocking Yes Yes Yes Limited 385K+ domains
Portable (travels with laptop) No (appliance) No (appliance) Cloud only Cloud only Single binary
Developer overrides No No No No REST API + auto-expiry
Local service proxy No No No No .numa + HTTPS + WS
Data stays local Yes Yes Cloud Cloud 100% local
Zero config Complex Docker/setup Yes Yes Works out of the box
Self-sovereign DNS No No No No pkarr/DHT roadmap

How It Works

Query → Overrides → .numa TLD → Blocklist → Local Zones → Cache → Upstream

No DNS libraries. The wire protocol — headers, labels, compression pointers, record types — is parsed and serialized by hand. Runs on tokio + axum, async per-query task spawning.

Configuration reference

Roadmap

  • DNS proxy core — forwarding, caching, local zones
  • Developer overrides — REST API with auto-expiry
  • Ad blocking — 385K+ domains, live dashboard, allowlist
  • System integration — macOS + Linux, launchd/systemd, Tailscale/VPN auto-discovery
  • Local service proxy — .numa domains, HTTP/HTTPS proxy, auto TLS, WebSocket
  • pkarr integration — self-sovereign DNS via Mainline DHT (15M nodes)
  • Global .numa names — self-publish, DHT-backed, first-come-first-served

License

MIT