agentic-dns

Agentic AI-Native DNS Routing, Diagnostics & Telemetry. Manages a complete DNS resolution chain (Pi-hole -> CoreDNS -> dnsdist -> Unbound/Stubby/DNSCrypt -> VPN DNS) with CLI, REST API, stdio MCP, and a Rust DoT/mTLS proxy server. Pure POSIX Bash + standard Unix tools -- zero Python/Node dependencies.

OCI Container (GHCR)

Pre-built multi-architecture images (linux/amd64, linux/arm64) for ephemeral agent sandboxes and headless runners.

Pulling the Image

# Pinned release
docker pull ghcr.io/dedsecorg/agentic-dns:1.6.0

# Moving major release
docker pull ghcr.io/dedsecorg/agentic-dns:v1

# Latest tracking branch
docker pull ghcr.io/dedsecorg/agentic-dns:latest

Running the Resolver Health & Trace Tools

# Quick health check
docker run --rm \
  --cap-add=NET_ADMIN \
  ghcr.io/dedsecorg/agentic-dns:v1 status

# Run trace check against host resolver
docker run --rm \
  --cap-add=NET_ADMIN \
  --network=host \
  ghcr.io/dedsecorg/agentic-dns:v1 trace api.anthropic.com

Context7 Documentation

This repository is indexed on Context7 with 134 code snippets for AI-assisted development. Use the Context7 MCP server or visit the link above for searchable documentation.

# Query via Context7 MCP
# "How to install agentic-dns?"
# "agentic-dns commands reference"
# "DNS chain architecture"

Why This Exists

Modern networks run multiple DNS layers simultaneously: Pi-hole for blocking, CoreDNS for split-horizon, dnsdist for load balancing, Unbound for recursive resolution, Stubby/DNSCrypt for DoT/DoH, plus VPN-provided DNS. When any layer fails or VPNs rotate DNS, resolution breaks silently.

agentic-dns treats the DNS chain as managed infrastructure:

1. Discovers topology -- detects running services, VPN DNS endpoints, listening ports

2. Health-checks each hop -- active DNS queries against every resolver

3. Auto-reconfigures -- rewrites dnsdist/CoreDNS upstreams when VPN DNS changes

4. Exposes telemetry -- REST API, MCP server, structured logs for AI agents

5. Provides DoT/mTLS proxy -- Rust server terminates TLS, forwards to chain

Related MCP server: dns-mcp

Architecture

                           +------------------+
                           |  Client Query    |
                           +--------+---------+
                                    |
                                    v
                           +------------------+
                           |  Pi-hole (53)    |  -- blocking, cache
                           |  forwarder       |
                           +--------+---------+
                                    |
                                    v
                           +------------------+
                           |  CoreDNS (5352)  |  -- split-horizon, local zones
                           +--------+---------+
                                    |
                                    v
                           +------------------+
                           |  dnsdist (5330)  |  -- load balance, retry, Lua policy
                           +--------+---------+
                    +--------+--------+--------+
                    |                 |        |
                    v                 v        v
             +------------+    +------------+  +------------+
             | Unbound    |    | Stubby     |  | DNSCrypt   |
             | (5335)     |    | (5360)     |  | (5354)     |
             | recursive  |    | DoT proxy  |  | DoH proxy  |
             +-----+------+    +-----+------+  +-----+------+
                   |                 |                |
                   +--------+--------+----------------+
                            |
                            v
                   +------------------+
                   |  VPN DNS         |  -- discovered dynamically
                   |  (Proton/Nord/   |
                   |   Tailscale)     |
                   +------------------+

                           +------------------+
                           |  agentic-dns-    |  -- Rust DoT/mTLS proxy
                           |  server (853)    |     on 127.0.0.1 or Tailscale
                           +------------------+

Installation

Manual

git clone https://github.com/dedsecorg/agentic-dns
cd agentic-dns
sudo -S -p '' -S -p '' ./install.sh

Installs:

• /usr/local/bin/agentic-dns -- main CLI

• /usr/local/bin/agentic-dns-server -- Rust DoT/mTLS proxy (prebuilt or cargo build)

• /etc/agentic-dns/ -- configs for dnsdist, CoreDNS, Unbound, Stubby, DNSCrypt

• /etc/systemd/system/agentic-dns.service -- systemd unit

• /etc/systemd/system/agentic-dns-server.service -- Rust server unit

Smithery (for MCP clients)

npx -y @smithery/cli install @dedsecorg/agentic-dns

Commands

DNS Chain Services

VPN DNS Discovery

Automatically detects VPN DNS endpoints:

• ProtonVPN -- protonvpn status or NetworkManager proton0 interface

• NordVPN -- WireGuard config or nordvpn status

• Tailscale -- tailscale status --json magic DNS

• WireGuard -- wg show allowed IPs

Set manually: VPN_DNS=10.2.0.1 agentic-dns status

Configuration

/etc/agentic-dns/ -- Service Configs

Generated by install.sh, editable for custom zones/upstreams:

• dnsdist.conf -- routing rules, load balancing, Lua policies

• Corefile -- CoreDNS zones, plugins

• unbound.conf -- recursive resolver settings

• stubby.yml -- DoT upstream certificates

• dnscrypt-proxy.toml -- DoH server stamps

Environment Variables

MCP Integration

Start read-write MCP server:

agentic-dns mcp

Tools exposed:

• dns_status -- all services health + config

• dns_query -- resolve domain through chain

• dns_trace -- packet capture at each hop

• dns_route_add -- add dnsdist upstream

• dns_route_remove -- remove dnsdist upstream

• dns_bypass -- failover service

• dns_enforce -- phone DNS interception

• dns_pihole_log -- Pi-hole query log

REST API

The API is mTLS-only: socat terminates TLS 1.3 and requires a client cert signed by ca.crt before the handler runs. See docs/pki.md for generating the CA, server and per-agent client certs with openssl.

agentic-dns api
# or
curl --cacert /etc/agentic-dns/certs/ca.crt --cert agent.crt --key agent.key \
     https://localhost:8099/api/v1/status

Endpoints (all read-only; responses are {"status":"ok","text":"..."}):

• GET /api/v1/status -- full service status

• GET /api/v1/health -- health checks

• GET /api/v1/routes -- Pi-hole upstreams (pihole.toml) and dnsdist upstreams

• GET /api/v1/query?domain=example.com -- resolve

• GET /api/v1/trace?domain=example.com -- trace

• GET /api/v1/pihole/log -- Pi-hole logs

Mutations (route add/remove, bypass, enforce) are CLI/MCP-only and are deliberately not exposed over the network.

Phone DNS Interception (Android)

# On server (run as root)
agentic-dns enforce on 100.87.74.22

# On Android: set DNS to server Tailscale IP (100.74.31.18)
# All DoT (port 853) from phone -> Pi-hole -> chain

Uses nftables/iptables TPROXY + agentic-dns-server DoT proxy to transparently intercept encrypted DNS (port 853) and force through Pi-hole.

Rust DoT/mTLS Server

agentic-dns-server -- standalone binary:

• Terminates TLS on 853 (DoT) or 443 (DoH)

• Requires client certs chaining to --client-ca (mTLS, mandatory)

• Hybrid post-quantum key exchange only (X25519MLKEM768; --allow-classical-kx to also offer X25519)

• Forwards to local DNS chain

• Metrics on :9090/metrics (Prometheus)

• Zero-copy, async, ~2MB RAM

Build:

cd server && cargo build --release
# or download prebuilt from releases

Requirements

• Linux (systemd, nftables/iptables)

• Pi-hole, CoreDNS, dnsdist, Unbound, Stubby, DNSCrypt-Proxy installed

• dig, ss, jq, bash 4.4+

• Rust 1.75+ (for server build)

• CAP_NET_ADMIN, CAP_NET_BIND_SERVICE (for server)

License

MIT -- see LICENSE.

Related

• agentic-route -- kernel policy routing reconciler (same author)

• hermes-dns -- private fork with real IPs, same engine# Test payment notification test test2 test3