### Manual Installation

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

Clones the repository and executes the installation script with sudo privileges.

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

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

### Manual Installation via Git

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

Clone the repository and execute the installation script with sudo privileges.

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

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

### Verify Installation

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

Commands to check the status, trace a domain, and verify the installed version.

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

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

### Quick Install via Shell Script

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

Downloads the prebuilt binary from the latest release, installs it to /usr/local/bin/agentic-dns, and verifies system dependencies.

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

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

### 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 integrity, extracts the binary, and installs it to /usr/local/bin/.

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

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

### Full System Server Installation

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

Clones the repository and runs the install script to set up the CLI, Rust proxy, configuration directories, and systemd services.

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

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

### Enable and start services

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

Commands to enable, start, and check the status of the agentic-dns 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
```

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

### Install systemd units

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

Run the install script to create the necessary systemd unit files.

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

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

### Run Local Jekyll Development Server

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

Installs Ruby dependencies and starts the local Jekyll server for previewing documentation.

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

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

### Install via Smithery

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

Use the Smithery CLI to install the package for MCP clients.

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

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

### Smithery Installation

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

Installs the package for MCP clients using the Smithery CLI.

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

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

### Install agentic-dns via curl

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

Use this command to download and execute the installation script for agentic-dns.

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

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

### Start read-write MCP server

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

Command to initialize the MCP server.

```bash
agentic-dns mcp
```

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

### Build CLI from Source

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

Clones the repository and executes the install script to build the CLI.

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

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

### REST API Usage Examples

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

Examples of using curl to interact with the API for status checks, DNS queries, packet tracing, and adding upstream routes.

```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"}'
```

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

### Enable Systemd Services

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

Enable and start the main agentic-dns and server services using systemctl.

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

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

### Querying via Context7 MCP

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

Example queries for the Context7 MCP server to retrieve documentation and architectural information.

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

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

### Start read-write MCP server

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

Command to initialize the MCP server for agentic-dns.

```bash
agentic-dns mcp
```

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

### Verify host environment and service startup

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

Checks for OpenSSL support in socat, verifies OpenSSL version and KEM algorithm availability, confirms directory and key permissions, and starts the agentic-dns services.

```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"
```

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

### Install via Smithery

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

Adds agentic-dns as an MCP server to your client configuration using the Smithery CLI.

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

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

### Start MCP Server

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

Command to run the read-write stdio JSON-RPC 2.0 server compatible with MCP clients.

```bash
agentic-dns mcp
```

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

### GET /api/v1/query

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

Resolves a domain name.

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

### Description
Resolves the specified domain through the chain.

### Method
GET

### Endpoint
/api/v1/query

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

### Response
#### Success Response (200)
- **status** (string) - Status indicator
- **text** (string) - Resolution result
```

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

### Authenticate with client certificates

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

Examples for using client certificates with curl and kdig to authenticate against the agentic-dns service.

```bash
curl --cacert /etc/agentic-dns/certs/ca.crt \
     --cert ~/.agentic/hermes.crt --key ~/.agentic/hermes.key \
     https://127.0.0.1:8099/api/v1/status

# DoT (kdig / stubby / any DoT client that supports client certs):
kdig +tls +tls-ca=/etc/agentic-dns/certs/ca.crt \
     +tls-keyfile=~/.agentic/hermes.key +tls-certfile=~/.agentic/hermes.crt \
     @127.0.0.1 -p 853 example.com
```

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

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

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

### Build Rust DoT/mTLS Server from Source

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

Compiles the Rust server component and installs the binary 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
```

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

### Enable Systemd Services

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

Enables and starts the agentic-dns and agentic-dns-server systemd units.

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

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

### 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 the provided domain.

### Method
GET

### Endpoint
/api/v1/query

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

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

### GET /api/v1/query

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

Resolves a domain name.

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

### Description
Resolves a domain through the chain.

### Method
GET

### Endpoint
/api/v1/query

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

### Response
#### Success Response (200)
- **status** (string) - Status indicator
- **text** (string) - Resolution result
```

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

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

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

Retrieves Pi-hole logs.

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

### Description
Retrieve Pi-hole logs.

### Method
GET

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

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

### Install agentic-dns via Smithery CLI

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

Use this command to automatically configure the MCP server for AI clients like Claude Desktop or Cursor.

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

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

### GET /api/v1/trace

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

Traces the resolution path for a domain.

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

### Description
Traces the resolution for the provided domain.

### Method
GET

### Endpoint
/api/v1/trace

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

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

### Example MCP Session

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

JSON-RPC 2.0 message exchange between the client and the agentic-dns server.

```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":{}}}
```

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

### REST API server and client request

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

Commands to start the API server or perform a client request using mTLS.

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

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

### Run the agentic-dns-server with DoT proxy

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

Command to start the server in DoT proxy mode with required TLS certificates and upstream DNS configuration.

```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/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
```

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

### GET /api/v1/trace

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

Traces a domain resolution path.

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

### Description
Traces the resolution path for a domain.

### Method
GET

### Endpoint
/api/v1/trace

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

### Response
#### Success Response (200)
- **status** (string) - Status indicator
- **text** (string) - Trace details
```

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

### GET /api/v1/routes

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

Retrieves Pi-hole and dnsdist upstream configurations.

```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
- **text** (string) - Routing configuration details
```

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

### Start the API Server

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

Command to launch the agentic-dns API server. It listens on port 8099 by default, which can be overridden using the AGENTIC_DNS_API_PORT environment variable.

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

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

### GET /api/v1/routes

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

Retrieves Pi-hole and dnsdist upstream configurations.

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

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

### Method
GET

### Endpoint
/api/v1/routes
```

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

### GET /api/v1/routes

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

Retrieves Pi-hole and dnsdist upstream configurations.

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

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

### Method
GET

### Endpoint
/api/v1/routes

### Response
#### Success Response (200)
- **status** (string) - Status indicator
- **text** (string) - Route configuration details
```

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

### GET /api/v1/query

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

Resolves a domain name through the configured chain.

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

### Description
Resolve a domain through the chain.

### Method
GET

### Endpoint
/api/v1/query

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

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

### Add DNS Upstream via REST API

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

Example of adding a new DNS route by sending a POST request to the local REST API.

```bash
curl -X POST http://localhost:8099/api/v1/route   -H "Content-Type: application/json"   -d '{"name": "myresolver", "addr": "1.2.3.4:53"}'
```

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

### GET /api/v1/query

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

Resolves a domain name through the configured chain.

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

### Description
Resolve a domain through the configured chain.

### Method
GET

### Endpoint
/api/v1/query

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

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

### Build the agentic-dns-server binary

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

Commands to compile the server from source using cargo.

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

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

### GET /api/v1/trace

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

Traces a domain resolution.

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

### Description
Traces the resolution path for a domain.

### Method
GET

### Endpoint
/api/v1/trace

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

### Response
#### Success Response (200)
- **status** (string) - Status indicator
- **text** (string) - Trace results
```

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

### Build the agentic-dns-server

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

Instructions to build the server from source using cargo.

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

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

### Build the agentic-dns-server

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

Instructions to build the server from source using cargo or to obtain the prebuilt binary.

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

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

### Build the agentic-dns-server binary

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

Commands to build the server from source using cargo.

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

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

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

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

Retrieves Pi-hole query logs.

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

### Description
Returns the Pi-hole query logs.

### Method
GET

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

### Response
#### Success Response (200)
- **status** (string) - Status indicator
- **text** (string) - Log content
```

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

### Build Locally

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

Build the container image from the local source.

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

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

### Generate CA, Server, and Client Certificates with OpenSSL

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

This script initializes the directory structure, generates a 10-year CA, creates server certificates for 'api' and 'dot' services, and issues a 90-day client certificate for an agent named 'hermes'. Run these commands as root on the host owning the services.

```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')
```

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

### GET /api/v1/health

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

Performs a health check on the service.

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

### Description
Health checks for the service.

### Method
GET

### Endpoint
/api/v1/health
```

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

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

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

Retrieves Pi-hole query logs.

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

### Description
Retrieves the Pi-hole query logs.

### Method
GET

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

### Response
#### Success Response (200)
- **status** (string) - Status indicator
- **text** (string) - Log content
```

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

### GET /api/v1/health

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

Performs service health checks.

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

### Description
Performs health checks on the service.

### Method
GET

### Endpoint
/api/v1/health

### Response
#### Success Response (200)
- **status** (string) - Status indicator
- **text** (string) - Health status message
```

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

### GET /api/v1/status

Source: https://github.com/dedsecorg/agentic-dns/blob/main/README.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
- **text** (string) - Status message
```

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

### GET /api/v1/health

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

Performs health checks on the service.

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

### Description
Performs health checks.

### Method
GET

### Endpoint
/api/v1/health
```

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

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

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

### GET /api/v1/health

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

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)
- **status** (string) - Status indicator
- **text** (string) - Health details
```

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

### Check service status and configuration

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

Use these commands to inspect logs, verify Pi-hole status, check for port conflicts, and list configuration files.

```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/
```

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

### GET /api/v1/health

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

Performs a health check on the service.

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

### Description
Performs health checks on the service.

### Method
GET

### Endpoint
/api/v1/health
```

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

### GET /api/v1/status

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

Retrieves the full service status.

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

### Description
Retrieves the full service status.

### Method
GET

### Endpoint
/api/v1/status

### Response
#### Success Response (200)
- **status** (string) - Status indicator
- **text** (string) - Status details
```

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

### Troubleshoot VPN DNS detection

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

Verify VPN interface status and perform manual DNS overrides.

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

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

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

### Claude Desktop Configuration

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

Configuration snippet to add agentic-dns as an MCP server in Claude Desktop.

```json
{
  "mcpServers": {
    "agentic-dns": {
      "command": "agentic-dns",
      "args": ["mcp"]
    }
  }
}
```

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

### Docker Pull and Run

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

Pulls the multi-arch image from GHCR and runs the container with necessary network capabilities.

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

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

### GET /api/v1/trace

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

Traces a domain resolution request with packet capture.

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

### Description
Trace a domain resolution with packet capture.

### Method
GET

### Endpoint
/api/v1/trace

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

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

### Register New Service in bin/agentic-dns

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

Adding a new service to the SERVICES array in the agentic-dns binary configuration.

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

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

### GET /api/v1/status

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

Retrieves the full service status of the Agentic-DNS server.

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

### Description
Returns the full service status.

### Method
GET

### Endpoint
/api/v1/status
```

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

### Running Resolver Health and Trace Tools

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

Commands to execute health checks and DNS trace operations using the containerized agent. Requires NET_ADMIN capability.

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

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

### Trace DNS

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

Run the container with host networking and NET_ADMIN capability to trace a specific domain.

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

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

### GET /api/v1/trace

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

Performs a DNS resolution trace for a domain with packet capture.

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

### Description
Trace resolution with packet capture.

### Method
GET

### Endpoint
/api/v1/trace

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

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

### Verify DNS resolution and service hops

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

Test resolution paths and individual service ports using agentic-dns commands and dig.

```bash
# Check each hop
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
```

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

### Main CLI Hardening for agentic-dns.service

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

Configuration for the agentic-dns service to manage network capabilities and restrict system access.

```ini
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
ProtectSystem=strict
ReadWritePaths=/etc/agentic-dns /run/agentic-dns /etc/pihole
```

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

### Verify unauthenticated peer rejection

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

Use openssl to verify that the service rejects connections from peers without valid certificates.

```bash
openssl s_client -connect 127.0.0.1:853 -CAfile ca.crt </dev/null 2>&1 | grep alert
# expect: sslv3 alert handshake failure  (rustls: "peer sent no certificates")
```

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

### Main CLI Hardening for agentic-dns.service

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

Security configuration for the main agentic-dns service, granting specific network capabilities and restricting write access.

```ini
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
ProtectSystem=strict
ReadWritePaths=/etc/agentic-dns /run/agentic-dns /etc/pihole
```

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

### Accessing the REST API via CLI or curl

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

Shows how to access the API using the agentic-dns CLI or a curl command with the required mTLS certificates.

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

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

### View service logs

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

Use journalctl to follow the logs for the agentic-dns and agentic-dns-server services.

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

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

### Set Pi-hole API Key Environment Variable

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

Shows how to manually set the PIHOLE_API_KEY environment variable if it is not auto-detected from the default path.

```bash
# Auto-detected from /etc/pihole/pihole-api-key.txt
# Or set manually:
export PIHOLE_API_KEY="your-api-key"
```

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

### Run Daemon

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

Run the container in detached mode with host networking, volume mounting for configuration, and restart policy.

```bash
docker run -d   --name agentic-dns   --restart unless-stopped   --cap-add=NET_ADMIN   --network=host   -v /etc/agentic-dns:/etc/agentic-dns   ghcr.io/dedsecorg/agentic-dns:v1 daemon
```

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

### agentic-dns.service configuration

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

Configuration file for the agentic-dns daemon service.

```ini
[Unit]
Description=agentic-dns daemon
After=network.target
Wants=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/agentic-dns daemon
Restart=on-failure
RestartSec=5
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
NoNewPrivileges=true

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

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

### Systemd unit configuration for agentic-dns-server

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

A systemd service file to run the proxy server as a background process with necessary network capabilities.

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

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

### Manual VPN DNS Configuration

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

Manually set the VPN DNS server by providing the IP address via the VPN_DNS environment variable before running the status command.

```bash
VPN_DNS=10.2.0.1 agentic-dns status
```

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

### Check Container Status

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

Run the container with NET_ADMIN capability to check the status.

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

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

### Monitor resource usage

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

Check memory consumption and identify runaway processes.

```bash
# Rust server should use ~2MB RAM
ps aux | grep agentic-dns-server

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

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

### Enable debug mode

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

Increase verbosity for CLI and server processes to troubleshoot issues.

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

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