HydraDNS

HydraDNS

A self-hosted DNS firewall in Go. Blocks ads, malware and trackers network-wide, like Pi-hole. API-first control plane, a real dashboard, a CLI, and a built-in Model Context Protocol server so Claude or any MCP agent can manage policy for you.

Screenshots and product site at hydradns.app (a marketing site with static screenshots, not an interactive demo)

HydraDNS vs Pi-hole

Choose Pi-hole today for battle-tested stability, regex rules, and community support. Choose HydraDNS for a hackable Go codebase, an API-first control plane, and AI-agent management over MCP that self-hosted alternatives only get through third-party bridges.

Honest limits: like every DNS-layer filter, HydraDNS cannot stop a client that hardcodes a DoH server by raw IP. Pair it with a firewall rule on 443/853 to close that path. For the fuller list (no TLS on the dashboard/gRPC yet, no DNSSEC, regex/wildcard policies not enforced, and more), see docs/limitations.md.

Why HydraDNS

I spent 15 months building an enterprise next-generation firewall in Go, and kept wishing the self-hosted version of that tooling existed: something a home or small-office network could run, with a real API and a control plane you could drive from a script or an AI agent instead of a settings page. HydraDNS is that tool. The built-in Model Context Protocol server comes from the same work I do upstream as a CNCF Jaeger contributor, where I build MCP tooling for observability.

It is pre-1.0 and moving fast. If it is useful to you, a star and an issue both help.

Built by Roshan Singh (@lopster568).

Quick Start

# Clone (single repo, no submodules)
git clone https://github.com/hydradns/hydradns.git
cd hydradns

# Start everything
docker compose up -d

# Verify DNS is working
dig @localhost example.com

# Check the dashboard
open http://localhost:3000

Port 53 already in use? On Linux or WSL2, systemd-resolved may already hold port 53. Free it before starting: sudo systemctl disable --now systemd-resolved (then set a DNS server in /etc/resolv.conf), or edit the port mapping in docker-compose.yml. See docs/pi-deployment.md for details.

That's it. DNS filtering is active. Give this machine a static IP and point your router's DNS to it. See docs/pi-deployment.md for static IP setup on Linux, macOS, and Windows plus per-router DNS instructions.

Architecture

                    +-----------+
                    |  Browser  |
                    +-----+-----+
                          |
                    +-----v-----+
                    |  Dashboard |  :3000  (Next.js)
                    +-----+-----+
                          |
                    +-----v-----+
         +--------->  Control   |  :8080  (Go + Gin REST API)
         |          |   Plane   |
         |          +-----+-----+
         |                |  gRPC :50051
         |          +-----v-----+
  CLI/MCP|          |   Data    |  :53    (DNS UDP/TCP)
  hydra  +--------->   Plane    |
                    +-----+-----+
                          |
               +----------+----------+
               |          |          |
          +----v---+ +----v---+ +----v---+
          |Blocklist| | Policy | |Upstream|
          | Engine  | | Engine | |Resolvers|
          +--------+ +--------+ +--------+

DNS Query Pipeline

Every DNS query is scored by a heuristic threat detector (domain entropy, DGA-pattern, length, subdomain depth); scoring is non-blocking and only tags the query log, with no auto-block yet. The query then goes through this pipeline with early exit:

1. DoH bootstrap interception: known DoH provider bootstrap hostnames get NXDOMAIN so browsers fall back to system DNS
2. Blocklist check: in-memory membership test; if the domain is blocked, respond per BLOCK_RESPONSE (default: A/AAAA → 0.0.0.0/::; nxdomain and refused also available)
3. Policy evaluation: Bloom filter for O(1) negative lookup, then exact match. Highest priority wins
4. Response cache: TTL-respecting LRU for allowed queries; blocked/redirect responses are never cached
5. Upstream forward: pool-per-resolver with failover (1.5s per-attempt timeout, 2 retries)

Dashboard

The web dashboard at localhost:3000 lets you:

• View real-time query statistics (total, blocked, allowed, block rate)
• Toggle the DNS engine on/off
• Manage blocklist sources (add/remove/view domain counts)
• Create and delete DNS policies (block, allow, redirect)
• Search and filter query logs

CLI

The hydra CLI wraps the control plane API for terminal-based management.

# Build the CLI
cd apps/cli && go build -o hydra .

# First boot: create the admin account and store the API token
hydra setup

# Check status
hydra status

# Block a domain
hydra block ads.example.com

# View query logs
hydra logs

# Manage blocklists
hydra blocklists
hydra blocklists add --id steven-black --name "StevenBlack" \
  --url "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts"

# Manage policies
hydra policies
hydra policies delete my-policy-id

# Engine control
hydra engine enable
hydra engine disable

# View metrics
hydra metrics

Set HYDRA_API_URL to point at a remote instance (default: http://localhost:8080).

MCP Server (AI Integration)

HydraDNS includes a built-in Model Context Protocol server, letting AI assistants manage your DNS firewall conversationally.

# Start MCP server (JSON-RPC 2.0 over stdio)
hydra mcp

Claude Code Setup

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "hydradns": {
      "command": "/path/to/hydra",
      "args": ["mcp"],
      "env": {
        "HYDRA_API_URL": "http://localhost:8080"
      }
    }
  }
}

Available MCP Tools

Example conversation: Say "Block all social media domains" and Claude calls block_domain for each domain.

Development

Prerequisites

• Go 1.26+
• Node.js 20+
• Docker & Docker Compose

Working on a Service

Each service lives under apps/ in this repo. Work inside its directory:

cd apps/core
make build        # Compile controlplane & dataplane
make test         # Run tests with coverage
make fmt          # Format code
make vet          # Vet code
make lint         # golangci-lint

cd apps/ui
npm run dev       # Dev server on :3000
npm run build     # Production build

cd apps/cli
go build -o hydra .  # Build CLI binary

Full Stack Commands (from root)

make setup        # One-time local setup (.env)
make start        # docker compose up -d
make stop         # docker compose down
make update       # git pull --ff-only
make logs         # Tail all logs
make build-core   # Rebuild core service
make restart-core # Rebuild + restart core

Project Structure

hydradns/
├── apps/
│   ├── core/           # Go DNS engine + API
│   │   ├── cmd/        #   controlplane + dataplane binaries
│   │   ├── internal/   #   blocklist, dnsengine, policy, storage
│   │   ├── configs/    #   config.yaml + policies.json
│   │   └── proto/      #   gRPC protobuf definitions
│   ├── ui/             # Next.js dashboard
│   ├── scanner/        # Network detection worker
│   └── cli/            # CLI + MCP server
│       ├── cmd/        #   Cobra commands
│       ├── api/        #   HTTP client for control plane
│       └── mcp/        #   MCP JSON-RPC server
├── docker-compose.yml  # Full stack orchestration
├── Makefile            # Convenience commands
└── scripts/            # Setup scripts

Deployment

Docker Compose (recommended)

docker compose up -d

Core runs as a combined container (controlplane + dataplane) with:

• SQLite database persisted in a Docker volume
• Health check on /health endpoint
• Automatic blocklist fetching on startup

Raspberry Pi / VPS

curl -fsSL https://raw.githubusercontent.com/hydradns/hydradns/main/scripts/install.sh | bash

Then give the device a static IP and point your router's DNS server to it. Full walkthrough (static IP on Linux/macOS/Windows, router config): docs/pi-deployment.md.

Documentation

• Deployment Guide: install on a Raspberry Pi or any always-on machine; static IP setup (Linux, macOS, Windows), per-router DNS configuration, troubleshooting
• Hardware Guide: choosing a device to run HydraDNS on
• Known Limitations: what's not implemented yet, with impact and workarounds
• MCP Server Guide: the 14 tools, roles, and client configuration for the built-in MCP server
• Release Runbook: what release.yml publishes and how tags are cut
• Public Demo: hosting a read-only, public instance of the dashboard

Configuration

Contributing & Community

Contributions are welcome, HydraDNS is pre-1.0 and there is a lot to build.

• Contributing guide how to set up, build, and open a pull request
• Roadmap what is planned and where help is most useful
• Code of Conduct
• Security policy report vulnerabilities privately
• Changelog
• Discussions questions and ideas

License

Apache-2.0