agentic-dns

Motor de enrutamiento, diagnóstico y telemetría DNS nativo de POSIX para sistemas de IA agénticos (Claude, Cursor, Windsurf, Hermes Agent, Copilot).

agentic-dns es un motor de orquestación DNS ultrarrápido y sin dependencias, escrito en Bash y Rust puros. Diseñado para estaciones de trabajo de desarrolladores, homelabs, nodos de Kubernetes y agentes de IA autónomos, gestiona cadenas DNS de múltiples niveles (pihole -> coredns -> dnsdist -> unbound -> dnscrypt -> VPN DNS), ejecuta trazas de paquetes en vivo salto a salto (trace), evita automáticamente los upstreams que fallan (bypass) y expone un servidor stdio Model Context Protocol (MCP JSON-RPC) para asistentes de codificación de IA.

Opciones de instalación rápida

Opción 1: Script de 1 línea (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/dedsecorg/agentic-dns/main/install.sh | bash

Opción 2: Contenedor Docker (GHCR)

docker run -d --net=host ghcr.io/dedsecorg/agentic-dns:latest

Opción 3: Paquete Node.js / npx

npx agentic-dns status

Related MCP server: dns-mcp

Incorporación de agentes de IA en 60 segundos

agentic-dns proporciona soporte de protocolo MCP JSON-RPC listo para usar para agentes de IA.

1. Claude Code

claude mcp add agentic-dns agentic-dns mcp

2. Cursor / Windsurf / Copilot

Añade a tu proyecto o al archivo .mcp.json de usuario:

{
  "mcpServers": {
    "agentic-dns": {
      "command": "agentic-dns",
      "args": [
        "mcp"
      ],
      "env": {
        "PIHOLE_HOST": "127.0.0.1",
        "AGENTIC_DNS_API_PORT": "8099"
      }
    }
  }
}

3. Hermes Agent

Ejecuta hermes mcp add agentic-dns agentic-dns mcp.

Ejemplos de indicaciones para asistentes de IA

Una vez conectado, pide a tu asistente de codificación de IA:

• "Comprueba si algún resolutor DNS local de la cadena está caído o no saludable."

• "Traza la ruta de paquetes para github.com a través de las interfaces de loopback y salida."

• "Evita stubby y enruta el tráfico DNS a través de unbound."

• "Muestra estadísticas recientes de consultas de Pi-hole desde SQLite."

Características principales

• Cero dependencias externas: Ejecución de Bash POSIX puro + herramientas Unix estándar (dig, ss, tcpdump, nft, sqlite3, socat, jq). Cero uso de RAM en reposo.

• Protocolo de Contexto de Modelo (MCP) nativo: Expone dns_status, dns_query, dns_trace, dns_health, dns_routes, dns_pihole_log y dns_bypass a los agentes de IA.

• Trazado en vivo entre servicios (trace): Ejecuta capturas de tcpdump en segundo plano a través de interfaces de loopback y red para visualizar la progresión de saltos de paquetes y los cuellos de botella de latencia.

• Conmutación por error automatizada (bypass): Reescribe dinámicamente la configuración de dnsdist y recarga los demonios de enrutamiento para evitar resolutores que fallan en milisegundos.

• Intercepción de DNS cifrado (enforce): Aplica reglas nftables no destructivas para redirigir DNS privado (puerto DoT 853) y descartar Google DoQ (UDP/443).

• Servidor Rust de alto rendimiento (agentic-dns-server): Incluye el crate server/ para el manejo de proxy DoT/DoH y telemetría REST.

Pipeline de arquitectura de 6 niveles

  [Client / Mobile Device]
            |
            v
      pihole (:53)          <- Ad blocking & FTL SQLite telemetry
            |
            v
     coredns (:5352)        <- Split-horizon mesh zone routing (Tailscale / Nebula)
            |
            v
     dnsdist (:5330)        <- Dynamic load balancing & bypass failover policy
            |
   +--------+--------+
   |                 |
   v                 v
unbound (:5335)   dnscrypt-proxy (:5354) / stubby (:5360)
   |                 |
   v                 v
[VPN / Upstream]  [DoH / DoT Cloud Upstreams]

Referencia rápida de comandos CLI

# View active DNS chain status and listening ports
agentic-dns status

# Execute live inter-service packet trace
agentic-dns trace google.com

# Failover failing service to backup
agentic-dns bypass stubby unbound

# Check health of all DNS listeners
agentic-dns health

# View Pi-hole query logs
agentic-dns pihole-log

# Start REST API server on port 8099
agentic-dns api

# Start stdio MCP JSON-RPC Server
agentic-dns mcp

Licencia

MIT License - Gratuito y de código abierto.