Agentic DNS

https://github.com/dedsecorg/agentic-dns
Admin
Agentic DNS is an AI-native DNS routing, diagnostics, and telemetry engine that manages multi-tier...
Tokens:35,169
Snippets:335
Trust Score:7.5
License:MIT
Update:5 days ago
Show doc for...
Tokens:
Raw
### Enable and start services

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/systemd.md

Enable, start, and check the status of both systemd services.

```bash
sudo -S -p '' systemctl enable agentic-dns agentic-dns-server
sudo -S -p '' systemctl start agentic-dns agentic-dns-server
sudo -S -p '' systemctl status agentic-dns agentic-dns-server
```

--------------------------------

### Full System Install from Git

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/installation.md

Clones the repository and runs the install script with sudo. Installs the main CLI, the Rust DoT/mTLS proxy, configuration files, and systemd units.

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

--------------------------------

### Local Development Commands

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/github-pages.md

Run these commands to install dependencies and start the Jekyll server locally. The site will be available at http://localhost:4000.

```bash
bundle install
bundle exec jekyll serve
```

--------------------------------

### Verify Installation Commands

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/installation.md

Verifies the installation by checking status, tracing a domain, and displaying the version.

```bash
agentic-dns status
agentic-dns trace google.com
agentic-dns --version
```

--------------------------------

### Manual Install from Release Assets

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/installation.md

Downloads the release tarball and checksums, verifies the archive with sha256sum, then extracts and installs the binary to /usr/local/bin/agentic-dns.

```bash
# Download and verify
curl -fsSL -O https://github.com/dedsecorg/agentic-dns/releases/download/v1.6.0/agentic-dns-v1.6.0.tar.gz
curl -fsSL -O https://github.com/dedsecorg/agentic-dns/releases/download/v1.6.0/checksums.txt
sha256sum -c checksums.txt

# Extract and install
tar -xzf agentic-dns-v1.6.0.tar.gz
sudo install -m 755 agentic-dns /usr/local/bin/agentic-dns
```

--------------------------------

### Install systemd units

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/systemd.md

Run the install script with sudo to create the systemd units for agentic-dns.

```bash
sudo -S -p '' ./install.sh
```

--------------------------------

### Manual Installation via install.sh

Source: https://github.com/dedsecorg/agentic-dns/wiki/Installation

Clones the repository and runs the installation script. The sudo command uses the -S flag to read the password from stdin and -p '' to suppress the prompt.

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

--------------------------------

### MCP Server Start

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/index.md

Starts the read-write MCP server for Agentic DNS.

```APIDOC
## MCP Server Start

### Description
Starts the read-write MCP server for Agentic DNS.

### Command
```bash
agentic-dns mcp
```
```

--------------------------------

### Install agentic-dns via curl

Source: https://github.com/dedsecorg/agentic-dns/blob/main/llms.txt

One-line installation command that downloads and executes the install script from the agentic-dns repository. Requires curl and bash.

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

--------------------------------

### Query Context7 MCP for agentic-dns documentation

Source: https://github.com/dedsecorg/agentic-dns/blob/main/README.md

Query the Context7 MCP server for searchable documentation of this repository, which is indexed with 134 code snippets. The comments show example queries for installation, command reference, and DNS chain architecture.

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

--------------------------------

### MCP session example with initialize and tools/call

Source: https://github.com/dedsecorg/agentic-dns/blob/main/wiki/MCP-Integration.md

Example MCP session showing the initialize handshake and a tools/call request for dns_status. The comments indicate the direction of each message.

```json
// Client -> Server
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}

// Server -> Client
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{...}},"serverInfo":{"name":"agentic-dns","version":"1.1.0"}}}

// Client -> Server
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"dns_status","arguments":{}}}
```

--------------------------------

### Install via Smithery CLI

Source: https://github.com/dedsecorg/agentic-dns/wiki/Installation

Installs the agentic-dns MCP server via Smithery CLI for MCP clients. The -y flag auto-confirms the npx package installation.

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

--------------------------------

### Start MCP server with agentic-dns mcp

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/mcp-guide.md

Run this command to start the read-write MCP server. It exposes the tools listed on the page.

```bash
agentic-dns mcp
```

--------------------------------

### Build CLI from Source

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/installation.md

Builds the CLI from source by cloning the repository and running the install script.

```bash
git clone https://github.com/dedsecorg/agentic-dns
cd agentic-dns
sudo ./install.sh
```

--------------------------------

### REST API Server Start

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/index.md

Starts the REST API server. The API is mTLS-only and requires a client certificate signed by ca.crt.

```APIDOC
## REST API Server Start

### Description
Starts the REST API server. The API is mTLS-only and requires a client certificate signed by ca.crt.

### Command
```bash
agentic-dns api
```

### Authentication
mTLS with TLS 1.3, client certificate signed by ca.crt required.
```

--------------------------------

### GET /api/v1/trace?domain=example.com

Source: https://github.com/dedsecorg/agentic-dns/wiki/REST-API

Traces DNS resolution with packet capture.

```APIDOC
## GET /api/v1/trace

### Description
Traces DNS resolution with packet capture.

### Method
GET

### Endpoint
/api/v1/trace

### Parameters
#### Query Parameters
- **domain** (string) - Required - The domain to trace.

### Request Example
curl http://localhost:8099/api/v1/trace?domain=example.com

### Response
#### Success Response (200)
Trace information with packet capture.

#### Response Example
(No example provided in source)
```

--------------------------------

### Build Rust Server from Source

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/installation.md

Builds the Rust DoT/mTLS server in release mode and installs it to /usr/local/bin. Requires Rust 1.75+.

```bash
cd agentic-dns
cargo build --release
sudo install -m 755 target/release/agentic-dns-server /usr/local/bin/agentic-dns-server
```

--------------------------------

### GET /api/v1/query?domain=example.com

Source: https://github.com/dedsecorg/agentic-dns/wiki/REST-API

Resolves a domain through the DNS chain.

```APIDOC
## GET /api/v1/query

### Description
Resolves a domain through the DNS chain.

### Method
GET

### Endpoint
/api/v1/query

### Parameters
#### Query Parameters
- **domain** (string) - Required - The domain to resolve.

### Request Example
curl http://localhost:8099/api/v1/query?domain=example.com

### Response
#### Success Response (200)
Resolution result.

#### Response Example
(No example provided in source)
```

--------------------------------

### MCP session: initialize and tools/call

Source: https://github.com/dedsecorg/agentic-dns/wiki/MCP-Integration

Example MCP session showing the initialize handshake and a tools/call request. The first two messages are the client-server initialization exchange, and the third is a call to the dns_status tool.

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
```

```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{...}},"serverInfo":{"name":"agentic-dns","version":"1.1.0"}}}
```

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"dns_status","arguments":{}}}
```

--------------------------------

### Start the REST API server

Source: https://github.com/dedsecorg/agentic-dns/wiki/REST-API

Starts the REST API server. By default it listens on port 8099, which can be changed by setting the AGENTIC_DNS_API_PORT environment variable.

```bash
agentic-dns api
# Listens on port 8099 (configurable via AGENTIC_DNS_API_PORT)
```

--------------------------------

### Enable systemd Services

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/installation.md

Enables and starts the systemd services for the main agentic-dns and the Rust server.

```bash
sudo systemctl enable --now agentic-dns
sudo systemctl enable --now agentic-dns-server
```

--------------------------------

### Setup: Enforce DNS on server and configure Android

Source: https://github.com/dedsecorg/agentic-dns/wiki/Phone-DNS-Interception

Run as root on the server to enforce DNS for the phone's Tailscale IP. Then set the Android device's DNS to the server's Tailscale IP. All DoT (port 853) traffic from the phone is intercepted and chained to Pi-hole.

```bash
# 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
```

--------------------------------

### Docker / GHCR Multi-Arch Install and Run

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/installation.md

Pulls the multi-arch Docker image (linux/amd64, linux/arm64) and runs the agentic-dns status command with required capabilities and host networking.

```bash
# Pull latest
docker pull ghcr.io/dedsecorg/agentic-dns:latest

# Or pinned version
docker pull ghcr.io/dedsecorg/agentic-dns:v1.6.0

# Run
docker run --rm -it \
  --cap-add=NET_ADMIN --cap-add=NET_BIND_SERVICE \
  --network host \
  ghcr.io/dedsecorg/agentic-dns:latest agentic-dns status
```

--------------------------------

### Add New Service to SERVICES Array

Source: https://github.com/dedsecorg/agentic-dns/wiki/Architecture

Example line to add to the SERVICES array in bin/agentic-dns to integrate a new DNS service (e.g., Knot). Format: name|port|address|type|options.

```bash
"knot|53|127.0.0.1|authoritative|none"
```

--------------------------------

### Check logs and common issues for services not starting

Source: https://github.com/dedsecorg/agentic-dns/wiki/Troubleshooting

Use journalctl to view logs for agentic-dns and agentic-dns-server. Check Pi-hole status, port conflicts on relevant ports, and missing configs in /etc/agentic-dns/.

```bash
journalctl -u agentic-dns -n 50 --no-pager
journalctl -u agentic-dns-server -n 50 --no-pager

# Common issues:
# 1. Pi-hole not running
systemctl status pihole-FTL

# 2. Port conflicts
ss -tulnp | grep -E '53|5330|5335|5352|5354|5360|853'

# 3. Missing configs
ls -la /etc/agentic-dns/
```

--------------------------------

### agentic-dns mcp

Source: https://github.com/dedsecorg/agentic-dns/blob/main/llms.txt

Starts a stdio MCP JSON-RPC protocol server for AI agents.

```APIDOC
## agentic-dns mcp

### Description
Starts a stdio Model Context Protocol (MCP) JSON-RPC server for AI agents, exposing DNS management tools.

### Method
CLI command

### Command
`agentic-dns mcp`

### Usage Example
bash
agentic-dns mcp


### Response
Starts the MCP server on stdio.
```

--------------------------------

### GET /api/v1/pihole/log

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/index.md

Returns Pi-hole logs.

```APIDOC
## GET /api/v1/pihole/log

### Description
Returns Pi-hole logs.

### Method
GET

### Endpoint
/api/v1/pihole/log

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Log details

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### Enable agentic-dns systemd Services

Source: https://github.com/dedsecorg/agentic-dns/wiki/Installation

Enables and starts the main agentic-dns service and the Rust server service using systemd. Both commands use sudo with the -S flag and an empty prompt.

```bash
sudo -S -p '' systemctl enable --now agentic-dns
sudo -S -p '' systemctl enable --now agentic-dns-server
```

--------------------------------

### GET /api/v1/trace

Source: https://github.com/dedsecorg/agentic-dns/blob/main/wiki/REST-API.md

Traces a DNS query with packet capture. Provide the domain as a query parameter to get a detailed trace.

```APIDOC
## GET /api/v1/trace

### Description
Traces a DNS query with packet capture.

### Method
GET

### Endpoint
/api/v1/trace

### Parameters
#### Query Parameters
- **domain** (string) - Required - The domain to trace.

### Request Example

curl http://localhost:8099/api/v1/trace?domain=example.com


### Response
#### Success Response (200)
Trace information with packet capture.

```

--------------------------------

### REST API endpoint examples

Source: https://github.com/dedsecorg/agentic-dns/wiki/REST-API

Example curl commands for the REST API endpoints: status, query, trace, and adding an upstream route. The add upstream command sends a JSON payload with the upstream name and address.

```bash
# Full status
curl http://localhost:8099/api/v1/status

# Query
curl http://localhost:8099/api/v1/query?domain=example.com

# Trace
curl http://localhost:8099/api/v1/trace?domain=example.com

# Add upstream
curl -X POST http://localhost:8099/api/v1/route   -H "Content-Type: application/json"   -d '{"name": "backup", "addr": "1.1.1.1:53"}'
```

--------------------------------

### Checklist for a new host

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/pki.md

Run these checks before adding a new host. Verifies socat has OpenSSL support, OpenSSL >= 3.5 for post-quantum KEMs, ML-KEM availability, certificate directory permissions (0700 dir, 0600 keys), and starts both the API and the DoT proxy in the background, expecting both to log "mTLS".

```bash
socat -V | grep -q OPENSSL || echo "socat lacks OpenSSL: API cannot start"
openssl version                              # >= 3.5 for PQ KEM on the socat surface
openssl list -kem-algorithms | grep -qi mlkem && echo "PQ hybrid available to socat"
ls -l /etc/agentic-dns/certs                 # 0700 dir, 0600 keys
agentic-dns api &  agentic-dns-server --dot-proxy &   # both must log "mTLS"
```

--------------------------------

### Systemd unit for agentic-dns-server

Source: https://github.com/dedsecorg/agentic-dns/wiki/Rust-DoT-Server

Systemd unit file to run agentic-dns-server as a service. It starts the binary at /usr/local/bin/agentic-dns-server, restarts on failure, and grants only the CAP_NET_BIND_SERVICE capability with NoNewPrivileges enabled.

```ini
[Unit]
Description=agentic-dns DoT/mTLS proxy server
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/agentic-dns-server
Restart=always
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE
NoNewPrivileges=yes

[Install]
WantedBy=multi-user.target
```

--------------------------------

### GET /api/v1/query

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/rest-api.md

Resolves a domain name.

```APIDOC
## GET /api/v1/query

### Description
Resolves a domain name.

### Method
GET

### Endpoint
/api/v1/query

### Parameters
#### Query Parameters
- **domain** (string) - Required - The domain to resolve

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Resolution result

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### Start REST API and query status with curl

Source: https://github.com/dedsecorg/agentic-dns/blob/main/README.md

Starts the mTLS-only REST API and shows a curl request that requires a client certificate signed by ca.crt. The API is read-only and returns JSON responses like {"status":"ok","text":"..."}.

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

--------------------------------

### Agentic DNS API Documentation

Source: https://github.com/dedsecorg/agentic-dns/blob/main/README.md

This documentation covers the MCP tools exposed by the agentic-dns MCP server and the REST API endpoints that are available. The MCP server is started with `agentic-dns mcp`, and the REST API is started with `agentic-dns api`. All REST endpoints require mTLS authentication.

```APIDOC
## [MCP] dns_status

### Description
Exposes all services health and configuration status.

### Method
MCP Tool

### Endpoint
agentic-dns mcp

### Parameters
None.

### Response
- Status and configuration details of all services.

```

```APIDOC
## [MCP] dns_query

### Description
Resolves a domain through the DNS chain.

### Method
MCP Tool

### Endpoint
agentic-dns mcp

### Parameters
None explicitly documented.

### Response
- Resolution result for the domain.

```

```APIDOC
## [MCP] dns_trace

### Description
Performs packet capture at each hop.

### Method
MCP Tool

### Endpoint
agentic-dns mcp

### Parameters
None explicitly documented.

### Response
- Trace information with packet capture details at each hop.

```

```APIDOC
## [MCP] dns_route_add

### Description
Adds a dnsdist upstream route.

### Method
MCP Tool

### Endpoint
agentic-dns mcp

### Parameters
None explicitly documented.

### Response
- Confirmation of route addition.

```

```APIDOC
## [MCP] dns_route_remove

### Description
Removes a dnsdist upstream route.

### Method
MCP Tool

### Endpoint
agentic-dns mcp

### Parameters
None explicitly documented.

### Response
- Confirmation of route removal.

```

```APIDOC
## [MCP] dns_bypass

### Description
Failover service for DNS.

### Method
MCP Tool

### Endpoint
agentic-dns mcp

### Parameters
None explicitly documented.

### Response
- Failover status or result.

```

```APIDOC
## [MCP] dns_enforce

### Description
Phone DNS interception service.

### Method
MCP Tool

### Endpoint
agentic-dns mcp

### Parameters
None explicitly documented.

### Response
- Enforcement status or result.

```

```APIDOC
## [MCP] dns_pihole_log

### Description
Retrieves Pi-hole query log.

### Method
MCP Tool

### Endpoint
agentic-dns mcp

### Parameters
None explicitly documented.

### Response
- Pi-hole query log.

```

```APIDOC
## [GET] /api/v1/status

### Description
Returns full service status.

### Method
GET

### Endpoint
/api/v1/status

### Parameters
None explicitly documented.

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Always "ok"
- **text** (string) - Status details

#### Response Example
{
  "status": "ok",
  "text": "..."
}

```

```APIDOC
## [GET] /api/v1/health

### Description
Returns health checks.

### Method
GET

### Endpoint
/api/v1/health

### Parameters
None explicitly documented.

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Always "ok"
- **text** (string) - Health check details

#### Response Example
{
  "status": "ok",
  "text": "..."
}

```

```APIDOC
## [GET] /api/v1/routes

### Description
Returns Pi-hole upstreams (from pihole.toml) and dnsdist upstreams.

### Method
GET

### Endpoint
/api/v1/routes

### Parameters
None explicitly documented.

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Always "ok"
- **text** (string) - Route configurations

#### Response Example
{
  "status": "ok",
  "text": "..."
}

```

```APIDOC
## [GET] /api/v1/query?domain=example.com

### Description
Resolves a domain using the DNS chain.

### Method
GET

### Endpoint
/api/v1/query?domain=example.com

### Parameters
#### Query Parameters
- **domain** (string) - Required - Domain to resolve

### Request Example
GET /api/v1/query?domain=example.com

### Response
#### Success Response (200)
- **status** (string) - Always "ok"
- **text** (string) - Resolution result

#### Response Example
{
  "status": "ok",
  "text": "..."
}

```

```APIDOC
## [GET] /api/v1/trace?domain=example.com

### Description
Traces the DNS resolution path.

### Method
GET

### Endpoint
/api/v1/trace?domain=example.com

### Parameters
#### Query Parameters
- **domain** (string) - Required - Domain to trace

### Request Example
GET /api/v1/trace?domain=example.com

### Response
#### Success Response (200)
- **status** (string) - Always "ok"
- **text** (string) - Trace details

#### Response Example
{
  "status": "ok",
  "text": "..."
}

```

```APIDOC
## [GET] /api/v1/pihole/log

### Description
Returns Pi-hole query logs.

### Method
GET

### Endpoint
/api/v1/pihole/log

### Parameters
None explicitly documented.

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Always "ok"
- **text** (string) - Pi-hole logs

#### Response Example
{
  "status": "ok",
  "text": "..."
}

```

--------------------------------

### Systemd unit for agentic-dns-server

Source: https://github.com/dedsecorg/agentic-dns/blob/main/wiki/Rust-DoT-Server.md

Systemd unit file to run agentic-dns-server as a service. It starts the server with --dot-proxy, enables restart on failure, and grants only the CAP_NET_BIND_SERVICE capability.

```ini
[Unit]
Description=agentic-dns DoT/mTLS proxy server
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/agentic-dns-server --dot-proxy
Restart=always
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE
NoNewPrivileges=yes

[Install]
WantedBy=multi-user.target
```

--------------------------------

### GET /api/v1/pihole/log

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/rest-api.md

Retrieves Pi-hole logs.

```APIDOC
## GET /api/v1/pihole/log

### Description
Returns Pi-hole logs.

### Method
GET

### Endpoint
/api/v1/pihole/log

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Log content

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### GET /api/v1/pihole/log

Source: https://github.com/dedsecorg/agentic-dns/wiki/REST-API

Retrieves Pi-hole logs.

```APIDOC
## GET /api/v1/pihole/log

### Description
Retrieves Pi-hole logs.

### Method
GET

### Endpoint
/api/v1/pihole/log

### Response
#### Success Response (200)
Pi-hole logs.

#### Response Example
(No example provided in source)
```

--------------------------------

### GET /api/v1/trace

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/index.md

Traces DNS resolution through the chain.

```APIDOC
## GET /api/v1/trace

### Description
Traces DNS resolution through the chain.

### Method
GET

### Endpoint
/api/v1/trace

### Parameters
#### Query Parameters
- **domain** (string) - Required - Domain to trace

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Trace details

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### Run agentic-dns-server in DoT proxy mode

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/rust-dot-server.md

Starts the server in DoT proxy mode, terminating TLS on port 853. Requires client certificates chaining to --client-ca (mTLS mandatory), and forwards to the specified upstream DNS. Keys may be PKCS#8, SEC1, or PKCS#1 PEM.

```bash
agentic-dns-server --dot-proxy \
  --cert-file /etc/agentic-dns/certs/dot.crt \
  --key-file  /etc/agentic-dns/certs/dot.key \
  --client-ca /etc/agentic-dns/certs/ca.crt \
  --upstream-dns 127.0.0.1 --dot-port 853
```

--------------------------------

### GET /api/v1/query

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/index.md

Resolves a domain through the DNS chain.

```APIDOC
## GET /api/v1/query

### Description
Resolves a domain through the DNS chain.

### Method
GET

### Endpoint
/api/v1/query

### Parameters
#### Query Parameters
- **domain** (string) - Required - Domain to resolve

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Resolution result

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### GET /api/v1/routes

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/rest-api.md

Retrieves Pi-hole upstreams and dnsdist upstreams.

```APIDOC
## GET /api/v1/routes

### Description
Returns Pi-hole upstreams (pihole.toml) and dnsdist upstreams.

### Method
GET

### Endpoint
/api/v1/routes

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Route information

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### GET /api/v1/routes

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/index.md

Returns Pi-hole upstreams and dnsdist upstreams.

```APIDOC
## GET /api/v1/routes

### Description
Returns Pi-hole upstreams and dnsdist upstreams.

### Method
GET

### Endpoint
/api/v1/routes

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Route details

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### GET /api/v1/status

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/index.md

Returns full service status.

```APIDOC
## GET /api/v1/status

### Description
Returns full service status.

### Method
GET

### Endpoint
/api/v1/status

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Status details

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### agentic-dns api

Source: https://github.com/dedsecorg/agentic-dns/blob/main/llms.txt

Starts a local REST HTTP API server on port 8099.

```APIDOC
## agentic-dns api

### Description
Starts a local REST HTTP API server on port 8099, providing programmatic access to agentic-dns functionality.

### Method
CLI command

### Command
`agentic-dns api`

### Usage Example
bash
agentic-dns api


### Response
Starts the HTTP API server on port 8099.
```

--------------------------------

### GET /api/v1/status

Source: https://github.com/dedsecorg/agentic-dns/wiki/REST-API

Returns the full service status of the agentic-dns system.

```APIDOC
## GET /api/v1/status

### Description
Returns the full service status of the agentic-dns system.

### Method
GET

### Endpoint
/api/v1/status

### Response
#### Success Response (200)
Full service status information.

#### Response Example
(No example provided in source)
```

--------------------------------

### GET /api/v1/query

Source: https://github.com/dedsecorg/agentic-dns/blob/main/wiki/REST-API.md

Resolves a DNS query through the agentic-dns chain. Provide the domain as a query parameter to get the resolution result.

```APIDOC
## GET /api/v1/query

### Description
Resolves a DNS query through the agentic-dns chain.

### Method
GET

### Endpoint
/api/v1/query

### Parameters
#### Query Parameters
- **domain** (string) - Required - The domain to resolve.

### Request Example

curl http://localhost:8099/api/v1/query?domain=example.com


### Response
#### Success Response (200)
Resolution result.

```

--------------------------------

### GET /api/v1/status

Source: https://github.com/dedsecorg/agentic-dns/blob/main/wiki/REST-API.md

Retrieves the full service status of the agentic-dns system. Use this endpoint to get an overview of the current state of the service.

```APIDOC
## GET /api/v1/status

### Description
Retrieves the full service status of the agentic-dns system.

### Method
GET

### Endpoint
/api/v1/status

### Response
#### Success Response (200)
Full service status information.

```

--------------------------------

### Build locally

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/container.md

Build the agentic-dns Docker image from the current directory.

```bash
docker build -t agentic-dns .
```

--------------------------------

### GET /api/v1/health

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/index.md

Returns health checks.

```APIDOC
## GET /api/v1/health

### Description
Returns health checks.

### Method
GET

### Endpoint
/api/v1/health

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Health check details

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### GET /api/v1/trace

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/rest-api.md

Traces a domain name.

```APIDOC
## GET /api/v1/trace

### Description
Traces a domain name.

### Method
GET

### Endpoint
/api/v1/trace

### Parameters
#### Query Parameters
- **domain** (string) - Required - The domain to trace

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Trace result

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### Build agentic-dns-server with cargo

Source: https://github.com/dedsecorg/agentic-dns/blob/main/README.md

Build the agentic-dns-server binary from source. Requires Rust 1.75+ and Linux with CAP_NET_ADMIN and CAP_NET_BIND_SERVICE capabilities.

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

--------------------------------

### Generate CA, server certs, and client certs with openssl

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/pki.md

Run as root on the host that owns the services. Creates a CA (10 years), per-service server certs (1 year) with SANs, and a client cert (90 days) for an agent. The CA key should be kept offline after issuing. The client cert uses an extfile to include extensions because rustls rejects X.509 v1 certificates.

```bash
umask 077
install -d -m 0700 /etc/agentic-dns/certs /etc/agentic-dns/certs/clients
cd /etc/agentic-dns/certs

# 1. CA (10 years). Keep ca.key offline after issuing.
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
  -days 3650 -subj "/CN=agentic-ca" -keyout ca.key -out ca.crt

# 2. One server cert per service (1 year). SAN must cover how clients dial it.
for svc in api dot; do
  openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
    -subj "/CN=agentic-dns-$svc" \
    -addext "subjectAltName=DNS:$(hostname),DNS:localhost,IP:127.0.0.1" \
    -keyout $svc.key -out $svc.csr
  openssl x509 -req -in $svc.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
    -days 365 -copy_extensions copy -out $svc.crt
  rm -f $svc.csr
done

# 3. One client cert per agent (90 days). Ship <agent>.crt+key to the agent
#    only; the CA never leaves this directory.
agent=hermes
openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
  -subj "/CN=agent-$agent" -keyout clients/$agent.key -out clients/$agent.csr
#    rustls (webpki) rejects X.509 v1 certificates, and `openssl x509 -req`
#    emits v1 unless extensions are present, so always pass an extfile.
openssl x509 -req -in clients/$agent.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -days 90 -out clients/$agent.crt \
  -extfile <(printf 'basicConstraints=CA:FALSE\nkeyUsage=digitalSignature\nextendedKeyUsage=clientAuth\n')

```

--------------------------------

### Build agentic-dns-server with cargo

Source: https://github.com/dedsecorg/agentic-dns/wiki/Rust-DoT-Server

Builds the agentic-dns-server binary from source. The resulting binary is located at target/release/agentic-dns-server, or a prebuilt version can be downloaded from releases.

```bash
cd server && cargo build --release
# Binary at target/release/agentic-dns-server
# Or download prebuilt from releases
```

--------------------------------

### GET /api/v1/health

Source: https://github.com/dedsecorg/agentic-dns/wiki/REST-API

Performs health checks on the service.

```APIDOC
## GET /api/v1/health

### Description
Performs health checks on the service.

### Method
GET

### Endpoint
/api/v1/health

### Response
#### Success Response (200)
Health check results.

#### Response Example
(No example provided in source)
```

--------------------------------

### Check VPN interfaces and manual override

Source: https://github.com/dedsecorg/agentic-dns/blob/main/wiki/Troubleshooting.md

Verify VPN interfaces (proton0, wg0) are present. Use VPN_DNS environment variable to manually override DNS for status command.

```bash
# Check VPN interfaces
ip link show proton0
ip link show wg0

# Manual override
VPN_DNS=10.2.0.1 agentic-dns status
```

--------------------------------

### GET /api/v1/health

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/rest-api.md

Retrieves health check results.

```APIDOC
## GET /api/v1/health

### Description
Returns health check results.

### Method
GET

### Endpoint
/api/v1/health

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Health check description

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### GET /api/v1/status

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/rest-api.md

Retrieves the full service status.

```APIDOC
## GET /api/v1/status

### Description
Returns the full service status.

### Method
GET

### Endpoint
/api/v1/status

### Response
#### Success Response (200)
- **status** (string) - Status indicator, e.g., "ok"
- **text** (string) - Status description

#### Response Example
{
  "status": "ok",
  "text": "..."
}
```

--------------------------------

### Check VPN interfaces and manual override

Source: https://github.com/dedsecorg/agentic-dns/wiki/Troubleshooting

Verify VPN interfaces with ip link show for proton0 and wg0. Use VPN_DNS environment variable to manually override DNS for agentic-dns status.

```bash
ip link show proton0
ip link show wg0

# Manual override
VPN_DNS=10.2.0.1 agentic-dns status
```

--------------------------------

### Enable debug mode for CLI and server

Source: https://github.com/dedsecorg/agentic-dns/wiki/Troubleshooting

Set AGENTIC_DNS_DEBUG=1 for verbose CLI output. Set RUST_LOG=debug for Rust server debug logging.

```bash
AGENTIC_DNS_DEBUG=1 agentic-dns status

# Rust server debug
RUST_LOG=debug agentic-dns-server
```

--------------------------------

### MCP Tool: dns_routes

Source: https://github.com/dedsecorg/agentic-dns/blob/main/llms.txt

Lists current dnsdist backend rules.

```APIDOC
## MCP Tool: dns_routes

### Description
Lists the current dnsdist backend rules via the MCP server.

### Method
MCP JSON-RPC tool

### Tool Name
`dns_routes`

### Usage
Callable via MCP JSON-RPC protocol.

### Response
Returns the list of dnsdist backend rules.
```

--------------------------------

### MCP Tool: dns_status

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/index.md

Returns all services health and configuration.

```APIDOC
## MCP Tool: dns_status

### Description
Returns all services health and configuration.

### Tool Name
`dns_status`
```

--------------------------------

### Audit commands for verifying hardening

Source: https://github.com/dedsecorg/agentic-dns/wiki/Security-Hardening

Shell commands to verify capabilities, systemd hardening properties, and file permissions for the agentic-dns binaries and configuration directory.

```bash
# Verify capabilities
getcap /usr/local/bin/agentic-dns-server
getcap /usr/local/bin/agentic-dns

# Verify systemd hardening
systemctl show agentic-dns-server --property=CapabilityBoundingSet,NoNewPrivileges,ProtectSystem
systemctl show agentic-dns --property=CapabilityBoundingSet,ProtectSystem

# Verify file permissions
ls -la /usr/local/bin/agentic-dns* /etc/agentic-dns/
```

--------------------------------

### View service logs

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/systemd.md

Follow the logs for the agentic-dns and agentic-dns-server services.

```bash
journalctl -u agentic-dns -f
journalctl -u agentic-dns-server -f
```

--------------------------------

### Enable debug mode

Source: https://github.com/dedsecorg/agentic-dns/blob/main/wiki/Troubleshooting.md

Set AGENTIC_DNS_DEBUG=1 for verbose CLI output, or RUST_LOG=debug for Rust server debug logging.

```bash
# Verbose CLI
AGENTIC_DNS_DEBUG=1 agentic-dns status

# Rust server debug
RUST_LOG=debug agentic-dns-server
```

--------------------------------

### MCP Tool: dns_trace

Source: https://github.com/dedsecorg/agentic-dns/blob/main/llms.txt

Spawns a live packet capture trace across inter-service hops.

```APIDOC
## MCP Tool: dns_trace

### Description
Spawns a live packet capture trace across inter-service hops via the MCP server.

### Method
MCP JSON-RPC tool

### Tool Name
`dns_trace`

### Usage
Callable via MCP JSON-RPC protocol.

### Response
Returns trace data showing packet hop progression.
```

--------------------------------

### Check high CPU/memory usage

Source: https://github.com/dedsecorg/agentic-dns/wiki/Troubleshooting

Check the Rust server process with ps aux, expecting ~2MB RAM. Use top with pgrep to monitor the bash CLI for runaway loops.

```bash
ps aux | grep agentic-dns-server

# Check for runaway loops in bash CLI
top -p $(pgrep -f agentic-dns)
```

--------------------------------

### GET /api/v1/pihole/log

Source: https://github.com/dedsecorg/agentic-dns/blob/main/wiki/REST-API.md

Retrieves Pi-hole logs. Use this endpoint to access logs from the Pi-hole integration.

```APIDOC
## GET /api/v1/pihole/log

### Description
Retrieves Pi-hole logs.

### Method
GET

### Endpoint
/api/v1/pihole/log

### Response
#### Success Response (200)
Pi-hole logs.

```

--------------------------------

### GET /api/v1/health

Source: https://github.com/dedsecorg/agentic-dns/blob/main/wiki/REST-API.md

Performs health checks for the service. Use this endpoint to verify that the service is running and healthy.

```APIDOC
## GET /api/v1/health

### Description
Performs health checks for the service.

### Method
GET

### Endpoint
/api/v1/health

### Response
#### Success Response (200)
Health check results.

```

--------------------------------

### Run agentic-dns status and trace in Docker

Source: https://github.com/dedsecorg/agentic-dns/blob/main/README.md

Run the resolver health and trace tools in a container. The status command performs a quick health check; the trace command runs a trace check against the host resolver and requires --network=host. Both need the NET_ADMIN capability.

```bash
docker run --rm \
  --cap-add=NET_ADMIN \
  ghcr.io/dedsecorg/agentic-dns:v1 status
```

```bash
docker run --rm \
  --cap-add=NET_ADMIN \
  --network=host \
  ghcr.io/dedsecorg/agentic-dns:v1 trace api.anthropic.com
```

--------------------------------

### Enable DNS interception

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/phone-dns-interception.md

Run on the server as root to enable interception for the phone's Tailscale IP. Plain text DNS is not covered, only port 853.

```bash
agentic-dns enforce on 100.87.74.22
```

--------------------------------

### Declare DNS services in SERVICES array

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/ARCHITECTURE.md

Defines the multi-tier DNS pipeline services in a pipe-delimited format. Each line specifies name, port, bind address, role, and upstream targets. Adding a new DNS daemon requires appending a single metadata line to this array.

```bash
SERVICES=(
    "pihole|53|127.0.0.1|forwarder|coredns"
    "coredns|5352|127.0.0.1|split-horizon|dnsdist"
    "dnsdist|5330|127.0.0.1|loadbalancer|unbound,dnscrypt"
    "unbound|5335|127.0.0.1|resolver|vpn-dns"
    "stubby|5360|127.0.0.1|dot-proxy|vpn-dns|unbound"
    "dnscrypt|5354|127.0.0.1|doh-proxy|cloudflare-doh"
    "vpn-dns|53|${VPN_DNS:-unknown}|upstream|none"
)
```

--------------------------------

### Check service logs and common issues

Source: https://github.com/dedsecorg/agentic-dns/blob/main/wiki/Troubleshooting.md

Use journalctl to view recent logs for agentic-dns and agentic-dns-server. Also check Pi-hole status, port conflicts on DNS-related ports, and verify config files exist.

```bash
# Check logs
journalctl -u agentic-dns -n 50 --no-pager
journalctl -u agentic-dns-server -n 50 --no-pager

# Common issues:
# 1. Pi-hole not running
systemctl status pihole-FTL

# 2. Port conflicts
ss -tulnp | grep -E '53|5330|5335|5352|5354|5360|853'

# 3. Missing configs
ls -la /etc/agentic-dns/
```

--------------------------------

### Manual MCP client configuration for agentic-dns

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/smithery.md

Add this configuration to your MCP client config file to manually set up the agentic-dns server. It specifies the command and arguments to run the server via npx.

```json
{
  "mcpServers": {
    "agentic-dns": {
      "command": "npx",
      "args": ["-y", "@smithery/cli", "run", "@dedsecorg/agentic-dns"],
      "env": {}
    }
  }
}
```

--------------------------------

### Test DNS resolution at each hop

Source: https://github.com/dedsecorg/agentic-dns/wiki/Troubleshooting

Use agentic-dns query and trace to check resolution. Then test individual services with dig on their respective ports: Pi-hole on 53, CoreDNS on 5352, dnsdist on 5330, Unbound on 5335, and Stubby on 5360 with TLS.

```bash
agentic-dns query example.com
agentic-dns trace example.com

# Test individual services
dig @127.0.0.1 -p 53 example.com      # Pi-hole
dig @127.0.0.1 -p 5352 example.com    # CoreDNS
dig @127.0.0.1 -p 5330 example.com    # dnsdist
dig @127.0.0.1 -p 5335 example.com    # Unbound
dig @127.0.0.1 -p 5360 +tls example.com # Stubby
```

--------------------------------

### MCP Tool: dns_pihole_log

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/index.md

Returns Pi-hole query log.

```APIDOC
## MCP Tool: dns_pihole_log

### Description
Returns Pi-hole query log.

### Tool Name
`dns_pihole_log`
```

--------------------------------

### Run agentic-dns status and trace in Docker

Source: https://github.com/dedsecorg/agentic-dns/blob/main/docs/index.md

Run the resolver health and trace tools in a container. Requires the NET_ADMIN capability; the trace command also needs host networking to check the host resolver.

```bash
# 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
```
Tokens:
Raw