Start here: Standalone installation. Manage private DNS records, service names, filtering and optional replication. A native install can also serve DHCP. KyIdentity and KyRecovery are optional. Verify DNS over both UDP and TCP before changing client resolver settings; the web health page does not test DNS resolution.
KyDNS is a self-hosted local DNS server and service directory for homes, homelabs, and small teams.
Its primary job is to make private services easy to name and reach. It also provides opt-out DNS blackhole filtering with built-in and operator-managed lists.
KyDNS can pair with KyRecovery using a one-time six-digit code and back itself up automatically; see Backups below.
Container-local installer setup and exact KyIdentity administrator grants are documented in INSTALLER_SETUP.md.
Register a service once:
kydns service add kypost \
--address 192.168.1.20 \
--alias webmail \
--check https://kypost.home.arpa/healthClients can then use:
kypost.home.arpa
webmail.home.arpa
without manually maintaining hosts files or opaque DNS rewrite rules.
KyDNS is licensed under the MIT License. The web UI carries the notice and serves the full license text from its About popover, so an operator can always see the terms of what they are running.
- Private service names, DNS records and per-network views.
- Blocklist filtering, encrypted upstream resolution and local DNSSEC validation.
- Service discovery and optional linked-node replication.
- An MCP endpoint so AI agents can explain blocks and manage rules.
- Optional DHCPv4 on supported native or host-network installations.
- Optional IPv6 DNS advertisement (RDNSS), so Android and other IPv6 clients use KyDNS too.
AI agents such as OpenClaw and Hermes Agent reach KyDNS over MCP at
https://<your host>/mcp, on the admin listener and never on the DNS port. Under
Settings → API tokens, create a token with the access AI agent and an access level:
- Read only (the default): the agent can explain why a name is blocked ("which list or rule matched"), read the totals and see the block lists with when each last updated.
- Read and write: it can also add or remove allow and deny rules, refresh the lists, and pause blocking for up to 60 minutes. Blocking resumes on its own.
- Can read the query log is a separate box, off by default, at either level. The query log is your network's browsing history: who looked up what, and when. It also covers the most-blocked names. Tick it only for an agent you would show that to.
The page shows the token once, with config for both agents that reads it from
KYDNS_AGENT_TOKEN, and the command to install the KyDNS skill (served at
/agent/skills/kydns/SKILL.md), which teaches the agent the tools and when to ask you first.
You can change an agent's access there later. An agent token unused for 90 days is revoked; an
agent token never works on the admin API, nor an admin token over MCP. No agent can change
upstream resolvers or listener settings. The admin UI, API and /mcp refuse browser
cross-origin requests and answer only to localhost, IP addresses and the names in
KYDNS_ADMIN_HOSTNAMES; see Running.
Domain names in the query log and in block lists are chosen by devices, websites and list maintainers, and an agent may treat them as instructions. KyDNS labels them as untrusted data, but give an agent write access only if you trust everyone who can message it. Details: AI agents.
- Backups — Backups.
- Features — What works today, Not yet, Scope, Repository status.
- Configuration — Configuration.
- Replication — Replication.
- Packages — Install from a package.
- Raspberry pi — Raspberry Pi SD image.
- Running — Running it.
- AI agents — MCP tools, access levels, the query log, pausing.
- Strong-key configuration — Supported TLS/key policy and existing-installation migration.
- Security model — Security model.
- Verifying releases — Check a release file or image's signature and source commit, and rebuild the binary to the same bytes.
- Assurance case — Threat model, trust boundaries, and why the security requirements are met.
Read the online manual or browse its Markdown sources.
Build and check it with mdbook build docs and python3 docs/check-links.py,
then open docs/book/index.html. The documentation workflow also provides a
downloadable documentation-book artifact.