Network-wide DNS filtering in the spirit of Pi-hole, rebuilt in Go: gRPC control plane, modern dashboard, DoH-bypass blocking, and an MCP server in the box so Claude or any AI agent can manage your network.
Block ads, malware, and trackers at the DNS level, before they ever reach your devices. Self-hosted, private, and fast.
| HydraDNS | Pi-hole | |
|---|---|---|
| Core | Go, gRPC control/data plane split | C (pihole-FTL), embedded web server |
| Setup | docker compose up, full stack in ~5 min |
installer script or Docker |
| AI management (MCP) | ✅ built in (hydra mcp, 9 tools: block/unblock, policies, logs, metrics) |
❌ third-party community bridges only |
| DoH bypass blocking | ✅ curated DoH bootstrap endpoints blocked at query time | |
| Policies | priority-based allow/block/redirect via API, UI, or CLI | groups, regex, and per-client rules (more mature today) |
| Maturity | young, pre-1.0, moving fast | 10+ years, huge community, built-in DHCP |
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.
# Clone with submodules
git clone --recursive 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:3000That'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.
+-----------+
| 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|
+--------+ +--------+ +--------+
| Service | Directory | Tech | Port |
|---|---|---|---|
| Core (Control + Data Plane) | apps/core |
Go 1.24, Gin, gRPC, GORM/SQLite | 8080, 53 |
| Dashboard | apps/ui |
Next.js 16, React 19, TypeScript, Tailwind | 3000 |
| Landing Page | apps/landing |
Vite, React 18, TypeScript | 3001 |
| Scanner | apps/scanner |
Go, network detection | — |
| CLI + MCP | apps/cli |
Go, Cobra, JSON-RPC 2.0 | — |
Every DNS query goes through a 3-step pipeline with early exit:
- Blocklist check — if domain is on any blocklist, respond
REFUSEDimmediately - Policy evaluation — Bloom filter for O(1) negative lookup, then exact match. Highest priority wins
- Upstream forward — pool-per-resolver with failover (5s timeout, 2 retries)
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
The hydra CLI wraps the control plane API for terminal-based management.
# Build the CLI
cd apps/cli && go build -o hydra .
# 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 metricsSet HYDRA_API_URL to point at a remote instance (default: http://localhost:8080).
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 mcpAdd to your Claude Code MCP config:
{
"mcpServers": {
"hydradns": {
"command": "/path/to/hydra",
"args": ["mcp"],
"env": {
"HYDRA_API_URL": "http://localhost:8080"
}
}
}
}| Tool | Description |
|---|---|
get_status |
Engine status and query statistics |
toggle_engine |
Enable or disable DNS engine |
block_domain |
Block a domain (creates a policy) |
unblock_domain |
Remove a block policy |
list_policies |
List all DNS policies |
list_blocklists |
List blocklist sources |
get_query_logs |
Recent DNS query logs |
get_metrics |
Latency percentiles and performance grade |
Example conversation: "Block all social media domains" — Claude calls block_domain for each domain.
- Go 1.24+
- Node.js 20+
- Docker & Docker Compose
Each service is a separate Git submodule. Work inside the service 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 binarymake setup # Initialize submodules
make start # docker compose up -d
make stop # docker compose down
make update # Pull latest submodule changes
make logs # Tail all logs
make build-core # Rebuild core service
make restart-core # Rebuild + restart corehydradns/
├── 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
│ ├── landing/ # Vite marketing site
│ ├── 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
docker compose up -dCore runs as a combined container (controlplane + dataplane) with:
- SQLite database persisted in a Docker volume
- Health check on
/healthendpoint - Automatic blocklist fetching on startup
curl -fsSL https://raw.githubusercontent.com/hydradns/hydradns/main/scripts/install.sh | bashThen 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.
- 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
| Env Variable | Default | Description |
|---|---|---|
PHANTOM_CONFIG |
configs/config.yaml |
Path to config file |
PHANTOM_DB |
phantomdns.db |
SQLite database path |
PHANTOM_POLICIES |
configs/policies.json |
Policy file path |
CORS_ORIGINS |
http://localhost:3000 |
Allowed CORS origins |
HYDRA_API_URL |
http://localhost:8080 |
CLI/MCP API target |