What is TelltaleDNS?
TelltaleDNS is a filtering DNS resolver for home and small networks, written in Rust and developed in the paimonsoror/telltaledns repository on GitHub. The project states its aim as an honest, real-time view of what the devices on a network are doing: each query is attributed to a named device, timed per processing stage and stored with the reason it was answered, blocked or forwarded. Filtering uses blocklists and per-device groups, DNS can be encrypted towards both clients and upstream resolvers, and the same software runs as a single node on a Raspberry Pi, inside Kubernetes, or as one cluster spanning both. According to the project FAQ, one maintainer builds it and runs it at home; the README states that Claude Code writes much of the code, tests and documentation, while the maintainer sets priorities and approves every release.
Each release publishes a static binary per architecture (x86_64, aarch64 and armv7 Linux), a minisign-signed SHA256SUMS file and a CycloneDX SBOM per binary. The container image ghcr.io/paimonsoror/telltale covers linux/amd64, linux/arm64 and linux/arm/v7, is about 13 MiB compressed, contains no shell and runs as an unprivileged user. A Helm chart is published as an OCI artifact for Kubernetes 1.26 and later. The operator guide lists the Raspberry Pi 3, 4, 5 and Zero 2 W as supported, with 64-bit or 32-bit OS; ARMv6 boards such as the Pi 1 and Zero W are not. There are no Windows or macOS builds. An edge channel is built from every commit on main.
The current release is TelltaleDNS 0.7.0, published on November 16, 2026; 0.1.0 appeared on October 7, 2026. Version 0.7.0 simplified the dashboard and added stub zones for internal domains, per-device mutes for anomaly findings, a support package that pseudonymises addresses and names by default, and a watchdog that writes a dump and exits with status 70 when a node stops answering for 60 seconds, so systemd, Compose or Kubernetes restarts it. Its known issues include a process hang with an unknown cause (issue #7) and early failures in DNSSEC validate mode with some DoT upstreams. The project is pre-1.0: releases before 1.0 can still change configuration keys and APIs, and each release note lists such changes.
The code is a Cargo workspace split into crates for the protocol, cache, filter, recursor, upstreams, cluster and API. Configuration is declarative TOML; users, sessions and tokens are kept in a SQLite state.db, and the query log is written as compressed hourly segment files. A web UI and REST API listen on port 8053, and Prometheus metrics on port 9153. The software is licensed under either the Apache License 2.0 or the MIT license, at the user's option, as stated in the LICENSE-APACHE and LICENSE-MIT files.
Some functions are out of scope by design. TelltaleDNS has no DHCP server: it reads device names from UniFi or OPNsense lease lists and from mDNS instead. The FAQ describes it as neither a firewall nor a network monitor, since it sees DNS lookups only. Local zones are meant for home and office use, without zone transfers or secondary zones. Importers cover Pi-hole and Technitium DNS Server configurations but not AdGuard Home. Similar self-hosted DNS filters on iThub include Pi-hole and Technitium DNS Server, the two projects the TelltaleDNS executive summary names as its inspiration.
Key capabilities
- Native install on a Raspberry Pi or Linux host The documented
install.shdownloads the binary for the CPU, checks the minisign signature and SHA-256, creates atelltalesystem user and installs a sandboxed systemd unit withProtectSystem=strict, onlyCAP_NET_BIND_SERVICEandMemoryMax=256M. In a terminal it offers a guided setup covering upstreams, starting blocklists, the first admin and query-log retention.telltale self-update --restartlater verifies and swaps the binary, and--uninstallrestores the previous resolver configuration. - Container image and Docker Compose
ghcr.io/paimonsoror/telltaleis taggedlatest, by version andedge. The Compose bundle uses host networking, a read-only root filesystem and onlyNET_BIND_SERVICE, and ships a starter config with encrypted upstreams, one balanced blocklist and a 7-day query log./var/lib/telltaleis the only path the container writes to. - Helm chart for Kubernetes The OCI chart
oci://ghcr.io/paimonsoror/charts/telltaleinstalls one StatefulSet (mode: allInOne) or a controller plus resolver pods (mode: scaled). The DNS Service usesexternalTrafficPolicy: Localso real client addresses reach the query log. Values switch on DoT, DoH and DoQ with cert-manager certificates, a ServiceMonitor, alert rules, a Grafana dashboard and a NetworkPolicy. - An explanation for every answer Each query-log row shows the device, the time taken per stage and how much of it was the upstream. Why? opens the decision: the list and line that blocked a name, the group, the route and the block response, including names reached through a CNAME. The same explanation is available for any name and device on the Explain page and at
GET /api/v1/explain. - Device names and identification Clients are named from UniFi or OPNsense lease lists, from what devices announce over mDNS, or by hand in the UI. The software also guesses a device type, such as a streaming player, camera or thermostat, from its maker and the names it looks up. Kubernetes workloads are listed as devices that keep their history across pod rollouts.
- Blocklists Lists can be URLs, local files or inline rules, in hosts, plain-domain, wildcard or AdBlock syntax (including
@@exceptions). They are compiled in the background into one index whose lookup cost does not grow with list size, then swapped in atomically. A download that loses more than half its lines is held by default, and a list in shadow mode is counted but never blocks. - Groups, schedules and per-device policy Groups map to networks or VLANs and carry their own lists, upstreams and block response. Further per-group options cover schedules by time of day and weekday, blocked services (TikTok, Roblox, Steam, Discord and others) without listing their domains, safe search for Google, Bing, DuckDuckGo, Yandex and YouTube Restricted Mode, rewrites, DNS64, filtering of IPv6 answers and rebinding protection.
- Quick rules and change simulation A quick rule allows or blocks a site for one device, a group or everyone, permanently or for a set time, and can be made from a query-log entry. Before saving a list, group, upstream, schedule or rule, What would this have done? replays the change over the stored query log and reports newly blocked, newly allowed and rerouted names with the devices affected.
- Encrypted DNS for devices Listeners for DNS over TLS (RFC 7858), DNS over HTTPS with HTTP/2 or HTTP/3 (RFC 8484) and DNS over QUIC (RFC 9250) accept Android Private DNS, browser and Apple profiles and other clients. Certificates are re-read within 10 seconds of a renewal. With a wildcard certificate a device configured as
kids-tablet.dns.example.comgets its own rules even on mobile data. PROXY protocol v2 is supported behind load balancers. - Encrypted upstreams and presets Upstreams can be plain UDP or TCP, DoT, DoH over HTTP/2 or HTTP/3, DoQ, DNSCrypt via
sdns://stamps, or routed through a proxy such as Tor. Upstream groups use thefailover,round_robin,weighted,fastestorparallelstrategy, with a circuit breaker per upstream.telltale presetsprints ready entries for Cloudflare, Google, Quad9, AdGuard, Mullvad, Control D, NextDNS and the Pi-hole presets. - Recursive resolution, stub zones and DNSSEC A
recursive://upstream resolves from the root servers with QNAME minimisation (RFC 9156), so no public resolver sees the lookups. Since 0.7.0 a stub zone starts an internal domain at its own authoritative servers. DNSSEC validation hasoff,permissiveandvalidatemodes, and conditional forwarding sends chosen domains and reverse zones to another server. - Local records and zones Local records answer A, AAAA, CNAME, PTR, TXT, MX and SRV names, with wildcards and automatic PTR records. Local zones make TelltaleDNS authoritative for a domain from an RFC 1035 zone file or inline records, and can be limited to some groups for split-horizon DNS.
telltale import zonereads a zone export. - Clustering across a Pi and Kubernetes The first node creates the cluster and its certificate authority; others join with a token and keep an mTLS link over HTTP/2. Configuration and compiled lists reach every node within seconds, and any node's UI shows the whole cluster. A small witness enables automatic failover, configuration can be pulled from Git with optional signed-commit checks, changes can go to canary nodes first with automatic rollback, and maintenance mode and failover drills are built in. DNS answering never depends on the cluster link.
- Dashboard and analytics The web UI includes a dashboard for the cluster, one node or one site, a traffic map, query and latency heatmaps, a flow view from groups to answers, change markers, service-level objectives, node comparison, a wall display and device anomaly findings. Every chart has a table view, and the UI works on phones.
- Metrics, exports and alerts Prometheus metrics are served on port 9153, with OpenTelemetry (OTLP) traces, dnstap and event sinks for SIEM collectors including Splunk HEC. Alerts can go to email, ntfy, Gotify, Slack-compatible channels or any webhook. A Grafana dashboard and Prometheus SLO rules are in the repository.
- Query log with privacy levels The on-disk log takes about 14 bytes per query, according to the documentation (50 million queries in about 690 MB), with retention by days and size. Privacy level 0 keeps everything, 1 stores names as keyed hashes, 2 also drops client addresses and 3 keeps no per-query log while counters and graphs continue. Configuration changes land in an audit log with a verifiable hash chain.
- Users, sign-in and HTTPS There is no default password: the first admin is created with a one-time setup token or a bootstrap secret. Roles are viewer, operator and admin, with optional TOTP two-factor sign-in, sign-in lockout and OpenID Connect providers such as Keycloak and Authentik. The UI and API are plain HTTP on port 8053 by default and can serve HTTPS with a self-signed or supplied certificate.
- REST API, CLI and MCP for agents The REST API is described by an OpenAPI 3.1 document at
/api/v1/openapi.jsonand includes a Server-Sent Events live query stream;telltale ctlexposes it in a shell. Each node also serves MCP over Streamable HTTP at/mcpand over stdio. Agent tokens carry scopes, can be limited to one group, need a reason header for every change and are rate limited; withrequire_approval, an agent's planned change waits for a person. The AI agents page lists the tools. - Migration, backup and support tooling
telltale import piholeconverts a Pi-hole v5 or v6 Teleporter export,gravity.dbor/etc/pihole, andtelltale import technitiumreads a running Technitium server through its API.telltale backup createworks while the service runs, optionally with the query log.telltale support-packagebuilds a redacted archive for bug reports, and nothing is uploaded automatically. - Published footprint and verifiable builds The README states an idle memory use of about 14 MiB, a million blocked names held in 60 MiB and 99.999 percent of cached and blocked answers sent within 250 µs under load, with the method in docs/v1-gate.md. Images are signed with cosign, and a nightly job checks that two builds of the same commit are identical. The daily update check reads a signed index and can be turned off.
Where TelltaleDNS fits
Replacing Pi-hole on a Raspberry Pi
The install page and operator guide describe installing the native systemd service on a Pi, then running telltale import pihole on a Teleporter export to turn upstreams, conditional forwarding, local records, adlists, allow and deny entries, groups and clients into TelltaleDNS configuration. Settings without an equivalent, such as the DHCP server, are listed in the output header. A recursive:// upstream can take the place of an Unbound instance running next to Pi-hole. The router's DHCP DNS setting is then pointed at the Pi so every device uses it.
Different rules for different parts of a home network
Groups are bound to networks or VLANs, for example a children's network, an IoT network and a work network, each with its own lists, upstreams, schedule, safe search setting and blocked services. Quick rules handle temporary exceptions for a single device. Before a change is saved, the simulation shows what it would have done to the previous day's queries, and the Explain view shows which rule decides for a given name and device.
Encrypted, filtered DNS for phones away from home
With a DoT, DoH or DoQ listener and a wildcard certificate, a phone set to a per-device hostname in Android Private DNS, or a DoH URL ending in a client ID, is recognised as the same device wherever it connects from, including mobile data. The encrypted DNS guide covers certificates from Let's Encrypt or cert-manager and the upstream side, where lookups leave the network over DoT, DoH or DoQ.
One DNS service across Kubernetes and a Pi
In the Helm chart's scaled mode, a controller StatefulSet holds configuration, compiled lists and the query log, and one LoadBalancer Service spreads queries over the controller and the resolver pods. A Raspberry Pi outside the cluster can join with a token, so DNS keeps answering if either side is down. Kubernetes workloads appear as devices grouped by namespace or pod label, and the Cluster page shows each node's role, version and sync state.
Finding out why a lookup failed or was slow
The query log can be filtered by name, device, status, response code, upstream and latency, and the live view streams matching queries. Per-stage timings separate filter, cache, upstream and DNSSEC time, upstream pages break failures down by kind, and service-level objectives show which devices and names spent the error budget. A support package collects health, upstream state, metrics and recent logs with pseudonymised addresses for an issue report.
Letting an AI agent work with network DNS
An agent token with read scopes lets an assistant query statistics, top lists, explanations and anomalies through MCP or the REST API. Write scopes allow it to propose quick rules, list or group changes as plans with a preview and optional simulation; with approval required, an operator accepts or rejects each plan on the Agent changes page, and every step is audited under the agent's token and its owner.
Install
curl -fsSLO https://raw.githubusercontent.com/paimonsoror/telltaledns/main/deploy/systemd/install.sh && sudo sh install.shReviews of TelltaleDNS
Be the first to share your experience with TelltaleDNS.
Write a review
Loading review form…
Found TelltaleDNS useful? Upvote it todayYour vote helps other IT teams find it in the daily ranking.







