From 9c313ef06a19fdad33bbe0480cedc2872ffec3fc Mon Sep 17 00:00:00 2001 From: Razvan Dimescu Date: Mon, 23 Mar 2026 21:16:50 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20reorder=20README=20for=20launch=20?= =?UTF-8?q?=E2=80=94=20lead=20with=20unique=20features,=20add=20install=20?= =?UTF-8?q?methods?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comparison table and "Why Numa" reordered so unique capabilities (service proxy, path routing, LAN discovery) appear first. Added brew/cargo install to Quick Start. Removed unshipped "Self-sovereign DNS" row from comparison table. Named hickory-dns and trust-dns in "How It Works" to signal deliberate architectural choice. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 9b7ad2e..b686dc8 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,9 @@ Built from scratch in Rust. Zero DNS libraries. RFC 1035 wire protocol parsed by ## Quick Start ```bash -# Install +# Install (pick one) +brew install razvandimescu/tap/numa +cargo install numa curl -fsSL https://raw.githubusercontent.com/razvandimescu/numa/main/install.sh | sh # Run (port 53 requires root) @@ -37,11 +39,11 @@ sudo ./target/release/numa ## Why Numa -- **Ad blocking that travels with you** — 385K+ domains blocked via [Hagezi Pro](https://github.com/hagezi/dns-blocklists). 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. +- **Local service proxy** — `https://frontend.numa` instead of `localhost:5173`. Auto-generated TLS certs, WebSocket support for HMR. Like `/etc/hosts` but with auto TLS, a REST API, LAN discovery, and auto-revert. - **Path-based routing** — `app.numa/api → :5001`, `app.numa/auth → :5002`. Route URL paths to different backends with optional prefix stripping. Like nginx location blocks, zero config files. - **LAN service discovery** — Numa instances on the same network find each other automatically via mDNS. Access a teammate's `api.numa` from your machine. Opt-in via `[lan] enabled = true`. - **Developer overrides** — point any hostname to any IP, auto-reverts after N minutes. REST API with 25+ endpoints. Built-in diagnostics: `curl localhost:5380/diagnose/example.com` tells you exactly how any domain resolves. +- **Ad blocking that travels with you** — 385K+ domains blocked via [Hagezi Pro](https://github.com/hagezi/dns-blocklists). Works on any network: coffee shops, hotels, airports. - **Sub-millisecond caching** — cached lookups in 0ms. Faster than any public resolver. - **Live dashboard** — real-time stats, query log, blocking controls, service management. LAN accessibility badges show which services are reachable from other devices. - **macOS + Linux** — `numa install` configures system DNS, `numa service start` runs as launchd/systemd service. @@ -128,15 +130,14 @@ bind_addr = "0.0.0.0:53" | | 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 | | Path-based routing | No | No | No | No | Prefix match + strip | | LAN service discovery | No | No | No | No | mDNS, opt-in | -| Data stays local | Yes | Yes | Cloud | Cloud | 100% local | +| Developer overrides | No | No | No | No | REST API + auto-expiry | +| Portable (travels with laptop) | No (appliance) | No (appliance) | Cloud only | Cloud only | Single binary | | Zero config | Complex | Docker/setup | Yes | Yes | Works out of the box | -| Self-sovereign DNS | No | No | No | No | pkarr/DHT roadmap | +| Ad blocking | Yes | Yes | Yes | Limited | 385K+ domains | +| Data stays local | Yes | Yes | Cloud | Cloud | 100% local | ## How It Works @@ -144,7 +145,7 @@ bind_addr = "0.0.0.0:53" 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. +No DNS libraries — no `hickory-dns`, no `trust-dns`. 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](numa.toml)