TelltaleDNS

See every question. Answer on your terms.

Every connection on your network starts with a DNS lookup. TelltaleDNS answers it in microseconds, filters it by your rules per device, and shows you exactly who asked, what they asked, and why it answered the way it did. It runs on a Raspberry Pi, in Kubernetes, or on both as one cluster that keeps answering even when parts of it fail.

A telltale is the strip of yarn sailors tie to a sail to see what the wind is really doing. DNS is your network's telltale: it reveals what every device is up to.

_{The dashboard on a demo network. Every device, name, and address in it is made up.}

Mission

Give everyone who runs a home or small network an honest, real-time view of what their devices are doing, and full control over it, without trading away speed, footprint, or reliability.

• See: every query is attributed to a device, explained, and timed per stage.
• Decide: your rules per device and group, enforced instantly at no performance cost.
• Never fail: DNS keeps answering from its last good config, whatever happens to the control plane.
• Run anywhere: the same artifact on a Pi, in a cluster, or both at once.

What it does

• Every answer explained. The query log ties each query to a named device, times every stage, and says why it was answered that way. Names come from your router, from what devices announce over mDNS, or from the UI, and TelltaleDNS recognizes what each device is (a Roku player, a camera, a thermostat) from its maker and the names it asks for.
• Your rules, per device. Blocklists, groups for each network or VLAN, schedules, safe search, blocked services, rewrites, and quick rules. Before you save a change, see what it would have done to yesterday's real traffic.
• Encrypted both ways. DoT, DoH, and DoQ for your devices and to your upstreams, DNSSEC validation, and full recursion when you'd rather not forward at all.
• Watch it work. A dashboard for the whole cluster, one node, or one site. A heatmap of when your network asks, a flow from each group to its answers, answer times as a heatmap, every change marked on every chart, and which devices and names spent the error budget. Compare nodes side by side, see a device's rhythm and its day, and put it all on a wall display. Device anomalies and alerts; Prometheus metrics, OpenTelemetry, dnstap, and event sinks for your SIEM.
• One cluster, many places. A Pi and Kubernetes nodes share one config and one management plane. A witness lets a replica take over automatically, and the config can live in Git. Changes can reach a few canary nodes first and roll back by themselves if those start failing, and maintenance mode takes a node out of service without dropped queries or false alarms.
• Private by design. Privacy levels decide how much of each query is kept, from everything to counters only, and every change lands in an audit log.
• Ready for agents. A documented REST API with OpenAPI, telltale ctl for the shell, and MCP tools with plans and approval for AI agents.
• Small and fast. One static binary in an image of about 13 MiB, for amd64, arm64, and 32-bit Pi OS. It idles at about 14 MiB of memory, holds a million blocked names in 60 MiB, and sends 99.999 % of cached and blocked answers within 250 µs of the query arriving, under load from another machine (measurements).
• Verifiable. Images are signed with cosign, each release binary carries its dependency list and an SBOM, and two builds of the same commit are identical (how to check).

Quick start

On a Raspberry Pi or any Linux host with Docker:

mkdir telltale && cd telltale
curl -fsSLO https://raw.githubusercontent.com/paimonsoror/telltaledns/main/deploy/compose/compose.yaml
curl -fsSLO https://raw.githubusercontent.com/paimonsoror/telltaledns/main/deploy/compose/telltale.toml
docker compose up -d
docker compose exec telltale telltale auth setup-token     # then open http://<host>:8053/

Kubernetes (Helm), a native systemd install, clustering, and moving from Pi-hole or Technitium are covered in docs/running.md.

Status: pre-1.0. Tagged releases are stable (latest), and edge is built from every commit on main. Releases before 1.0 can still change configuration keys and APIs, and their notes call out every such change; the roadmap shows what's next. Project site: https://paimonsoror.github.io/telltaledns/

Spec index

1. Overview: vision, goals, release-gate metrics
2. Requirements: numbered P0/P1/P2 contract
3. Architecture: roles, crates, threading, data flow
4. Resolution pipeline: listeners, cache, DNSSEC, recursion
5. Upstreams: protocols, presets, strategies, custom plugins
6. Filtering: list syntax, FST/DFA snapshots, groups, schedules
7. Observability: QueryEvent, metrics, query-log store, analytics
8. API and UI
9. Deployment, config, security: Helm, Pi, auth (local + OIDC)
10. Testing and benchmarks
11. Roadmap and tasks
12. Decisions (ADRs)
13. Clustering and HA
14. Agent API and MCP

Contributors ✨

Thank you to everyone who helps make TelltaleDNS better, whether by reporting what they found running it for real, writing code, or improving the docs:

Greg Pakes 💻 🐛 ⚠️

This project follows the all-contributors specification. Contributions of any kind are welcome: open an issue or a pull request.

Built with Claude

TelltaleDNS is developed with Claude Code, Anthropic's coding agent, working from this repository's specification under the maintainer's direction. Claude writes much of the code, tests, and documentation; the maintainer sets the priorities, decides what ships, and approves every release and rollout.

The history shows exactly where Claude took part: every commit it worked on carries a Co-Authored-By: Claude trailer, naming the model. git log --grep "Co-Authored-By: Claude" lists them.

License

Licensed under either of Apache License 2.0 or MIT, at your option.