Agentic Route

https://github.com/dedsecorg/agentic-route
Admin
Agentic Route is a declarative Linux kernel policy-routing reconciler that continuously monitors and...
Tokens:27,651
Snippets:240
Trust Score:7.2
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### Enable Daemon with systemctl

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

Enables and starts the agentic-route-daemon systemd service.

```bash
sudo -S -p '' systemctl enable --now agentic-route-daemon
```

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

### Manual Installation via Git Clone and install.sh

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

Recommended for servers. Clones the repository and runs the install script with sudo.

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

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

### Local Development Commands

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/github-pages.md

Install Ruby dependencies and start the Jekyll development server. Run these commands in the project root, then visit http://localhost:4000.

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

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

### Intent File Example

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

Example intent.json with forbidden_rules and pinned_routes. The daemon auto-applies within 200ms.

```json
{
  "forbidden_rules": [
    {"priority": 31580, "comment": "ProtonVPN catch-all"},
    {"priority": 31581, "comment": "ProtonVPN split-tunnel re-add"}
  ],
  "pinned_routes": [
    {"priority": 480, "table": 52, "dest": "100.64.0.0/10", "comment": "Tailscale"},
    {"priority": 32765, "table": 205, "dest": "0.0.0.0/0", "comment": "NordVPN egress"},
    {"priority": 100, "table": 100, "dest": "10.2.0.0/24", "via": "10.2.0.1", "comment": "ProtonVPN DNS"}
  ]
}
```

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

### Install via Smithery CLI

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

For MCP clients, installs the package using the Smithery CLI.

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

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

### Query agentic-route via Context7 MCP

Source: https://github.com/dedsecorg/agentic-route/blob/master/README.md

Use the Context7 MCP server to query agentic-route documentation. The comments show example queries for installation, commands reference, and intent.json schema.

```bash
# Query via Context7 MCP
# "How to install agentic-route?"
# "agentic-route commands reference"
# "intent.json schema"
```

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

### Check daemon logs and common fixes

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

Use journalctl to view the last 50 lines of daemon logs. Install inotify-tools if missing, verify CAP_NET_ADMIN capabilities in the service file, and clean up stale FIFO files from previous crashes.

```bash
# Check logs
journalctl -u agentic-route-daemon -n 50 --no-pager

# Common issues:
# 1. inotify-tools not installed
sudo -S -p '' apt-get install inotify-tools

# 2. Missing CAP_NET_ADMIN
# Check service file has:
# CapabilityBoundingSet=CAP_NET_ADMIN
# AmbientCapabilities=CAP_NET_ADMIN

# 3. FIFO cleanup from previous crash
ls -la /run/agentic-route/
# Remove stale FIFO if needed:
rm -f /run/agentic-route/events.fifo
```

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

### Install systemd units with install.sh

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/systemd.md

Run the install script to create systemd units. Uses sudo with no prompt.

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

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

### Enable and start agentic-route service

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/systemd.md

Enable the service to start on boot, start it immediately, and check its status.

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

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

### Example API requests

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

Shows example curl commands for the /api/v1/check, /api/v1/status, and /api/v1/enforce endpoints, with sample responses.

```bash
# Check drift
curl http://localhost:8099/api/v1/check
# {"clean": false}

# Get full status
curl http://localhost:8099/api/v1/status
# {"status": "ok", "text": "agentic-route status
Spec: /etc/agentic-route/routes.json
--- Desired rules ---
..."}

# Enforce reconciliation
curl http://localhost:8099/api/v1/enforce
# {"enforced": true}
```

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

### Checklist for a new host

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/pki.md

Run these commands to verify OpenSSL support, PQ KEM availability, certificate directory permissions, and that the API starts with 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-route/certs                 # 0700 dir, 0600 keys
agentic-route api &                          # must log "mTLS"
```

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

### Start MCP server

Source: https://github.com/dedsecorg/agentic-route/blob/master/README.md

Starts the read-only MCP JSON-RPC server for agentic-route.

```bash
agentic-route mcp
```

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

### Start REST API server

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/api-reference.md

Starts the REST API with mTLS. Listens on AGENTIC_ROUTE_API_PORT (default 8099). Requires client certificate chaining to AGENTIC_ROUTE_TLS_CA.

```bash
agentic-route api      # listens on AGENTIC_ROUTE_API_PORT (8099)
```

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

### Adding a New VPN - Intent JSON

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

Example intent.json for adding a new WireGuard VPN: one pinned_route and optional forbidden_rules.

```json
{
  "pinned_routes": [
    {"priority": 500, "table": 500, "dest": "0.0.0.0/0", "via": "10.8.0.1", "comment": "WireGuard egress"}
  ],
  "forbidden_rules": [
    {"priority": 501, "comment": "WireGuard auto-readd"}
  ]
}
```

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

### Example MCP session (initialize and tools/call)

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

Shows a client-server exchange: initialize handshake and a tools/call to route_status. The server responds with capabilities listing the four read-only tools and returns routing status.

```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":{"route_status":{...},"route_check":{...},"route_diff":{...},"route_trace":{...}}},"serverInfo":{"name":"agentic-route","version":"1.1.0"}}}

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

// Server -> Client
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"agentic-route status
Spec: /etc/agentic-route/routes.json

--- Desired rules ---
  480: from all to 100.64.0.0/10 lookup 52
..."}]}}
```

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

### Start the API server

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

Starts the agentic-route API server, which listens on port 8099 by default. The port can be changed with the AGENTIC_ROUTE_API_PORT environment variable.

```bash
agentic-route api
# Listens on port 8099 (configurable via AGENTIC_ROUTE_API_PORT)
```

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

### forbidden_rules priority gating example

Source: https://github.com/dedsecorg/agentic-route/wiki/Intent-File

Example of a forbidden rule with priority gating. Only deletes priority 31581 with that match; won't touch priority 32765 even if it has similar lookup.

```json
{ "prio": 31581, "match": "lookup 245447468" }
```

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

### API server implementation

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

Implements the API server using socat for TCP listening and delegates to CLI subcommands. Requires socat to be installed; otherwise, it exits with an error.

```bash
cmd_api() {
    local port="${AGENTIC_ROUTE_API_PORT:-8099}"
    if ! command -v socat >/dev/null 2>&1; then
        ar_die "socat is required for api"
    fi
    ar_log "API listening on :$port"
    while true; do
        socat TCP-LISTEN:"$port",reuseaddr,fork SYSTEM:"$0 api-handler" 2>/dev/null
    done
}

cmd_api_handler() {
    local path
    IFS=' ' read -r _ path _ || true
    printf 'HTTP/1.1 200 OK
Content-Type: application/json

'
    case "$path" in
        /api/v1/status) cmd_status 2>&1 | jq -Rs '{status:"ok", text:.}';;
        /api/v1/check) cmd_check >/dev/null 2>&1; printf '{"clean":%s}\n' "$([ "$?" -eq 0 ] && echo true || echo false)";;
        /api/v1/enforce) cmd_enforce >/dev/null 2>&1; echo '{"enforced":true}';;
        *) echo '{"error":"not found"}';;
    esac
}
```

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

### route_trace arguments

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/api-reference.md

JSON object for the route_trace tool. Requires 'target'; optional 'from'. Runs 'ip route get'.

```json
{ "target": "1.1.1.1", "from": "10.2.0.2" }
```

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

### GET /api/v1/enforce

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/api-reference.md

Applies the desired routing spec to the live state. This endpoint mutates kernel state.

```APIDOC
## GET /api/v1/enforce

### Description
Applies the desired routing spec to the live state. This endpoint mutates kernel state.

### Method
GET

### Endpoint
/api/v1/enforce

### Parameters
None

### Response
#### Success Response (200)
- **status** (string) - Always `ok`
- **corrected** (number) - Number of corrections applied

#### Response Example
```json
{"status":"ok","corrected":<n>}
```
```

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

### Multi-VPN intent.json configuration

Source: https://github.com/dedsecorg/agentic-route/wiki/Multi-VPN-Example

Defines routing coordination for NordVPN, ProtonVPN, and Tailscale. Includes forbidden rules to prevent VPN capture and hijacks, pinned routes for critical paths, and custom rules for traffic isolation. Use this JSON as the intent configuration to manage multiple VPNs without leaks or freezes.

```json
{
  "version": 1,
  "comment": "Multi-VPN stack: NordVPN egress, ProtonVPN DNS, Tailscale mesh",
  "forbidden_rules": [
    { "prio": 31580, "match": "suppress_prefixlength 0", "reason": "Proton suppress-bypass rule (ride-along with its capture)" },
    { "prio": 31581, "match": "lookup 245447468", "reason": "Proton split-tunnel capture: Proton is DNS-only, must not own host egress" },
    { "match": "100.64.0.0/10 lookup main", "reason": "Tailscale hijack: mesh CIDR must never route via main table" }
  ],
  "pinned_routes": [
    { "dst": "194.126.177.6/32", "via": "185.170.112.1", "dev": "eth0", "reason": "Pin Proton WG endpoint through eth0 so tunnel never loses handshake" },
    { "dst": "10.2.0.1/32", "dev": "proton0", "comment": "Proton DNS resolver strictly out proton0" },
    { "dst": "default", "via": "185.170.112.1", "dev": "eth0", "comment": "Bare-metal fallback egress (never let VPNs remove it)" }
  ],
  "custom_rules": [
    { "prio": 480, "selector": "from all to 100.64.0.0/10", "action": "lookup 52" },
    { "prio": 32765, "selector": "not from all fwmark 0xe1f1", "action": "lookup 205" }
  ]
}
```

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

### Debug drift not being corrected

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

Run a one-shot reconcile to see output, check the current state with jq, and verify intent.json is valid JSON.

```bash
# Run one-shot to see output
agentic-route-reconcile

# Check state
cat /run/agentic-route/state.json | jq .

# Verify intent.json is valid JSON
jq . /etc/agentic-route/intent.json
```

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

### Intent file JSON example

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/intent-file.md

Configuration file read by `agentic-route-reconcile` and `agentic-route-daemon`, overridable with `AGENTIC_ROUTE_INTENT`. Defines `forbidden_rules` (literal substring match, optionally scoped to `prio`), `pinned_routes` (re-added to `main` when VPN clients remove them), and `custom_rules` (added on top of discovered rules).

```json
{
  "version": 1,
  "forbidden_rules": [
    { "prio": 31580, "match": "suppress_prefixlength 0", "reason": "ProtonVPN capture rule" },
    { "match": "100.64.0.0/10 lookup main", "reason": "Never route the mesh via main" }
  ],
  "pinned_routes": [
    { "dst": "default", "via": "192.0.2.1", "dev": "eth0", "reason": "Keep fallback egress" }
  ],
  "custom_rules": [
    { "prio": 32765, "selector": "not from all fwmark 0xe1f1", "action": "lookup 205" }
  ]
}
```

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

### Monitor CPU usage and check for runaway loop

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

Use top to monitor the daemon's CPU usage; idle should be ~0% with spikes only on events. If high CPU, follow journalctl to look for rapid 'kernel routing event' logs without debounce.

```bash
# Check if debounce is working
# Should see ~0% CPU idle, spikes only on events
top -p $(systemctl show agentic-route-daemon --property=MainPID --value)

# If high CPU: check for runaway loop
journalctl -u agentic-route-daemon -f
# Look for rapid "kernel routing event" logs without debounce
```

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

### intent.json intent example

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/configuration.md

Constraints-only configuration for intent.json. Includes forbidden_rules, pinned_routes, and custom_rules. Used when VPN clients own most of the routing table and you only want to pin, forbid, or add a few things on top.

```json
{
  "version": 1,
  "forbidden_rules": [
    { "prio": 31580, "match": "suppress_prefixlength 0", "reason": "..." },
    { "match": "100.64.0.0/10 lookup main", "reason": "..." }
  ],
  "pinned_routes": [
    { "dst": "default", "via": "192.0.2.1", "dev": "eth0", "reason": "..." }
  ],
  "custom_rules": [
    { "prio": 32765, "selector": "not from all fwmark 0xe1f1", "action": "lookup 205" }
  ]
}
```

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

### GET /api/v1/diff

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/api-reference.md

Returns a detailed diff of the desired spec versus live state. This endpoint has no side effects.

```APIDOC
## GET /api/v1/diff

### Description
Returns a detailed diff of the desired spec versus live state. This endpoint has no side effects.

### Method
GET

### Endpoint
/api/v1/diff

### Parameters
None

### Response
#### Success Response (200)
- **status** (string) - Always `ok`
- **text** (string) - Diff text

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

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

### GET /api/v1/check

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

Checks for drift in the configuration. Returns a JSON object with a 'clean' boolean indicating whether the configuration is clean.

```bash
curl http://localhost:8099/api/v1/check
```

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

### MCP route_trace

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/api-reference.md

Runs `ip route get` for a target IP address, optionally from a source IP. The `target` argument is required.

```APIDOC
## MCP Tool: route_trace

### Description
Runs `ip route get` for a target IP address, optionally from a source IP. The `target` argument is required.

### Method
MCP tools/call

### Parameters
#### Request Body
- **target** (string) - Required - The destination IP address
- **from** (string) - Optional - The source IP address

### Request Example
```json
{ "target": "1.1.1.1", "from": "10.2.0.2" }
```

### Response
- **text** (string) - The output of `ip route get`
```

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

### Run daemon in debug mode

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

Run the daemon in the foreground with verbose output using HR_QUIET=0, or run reconcile with debug and check mode.

```bash
# Run daemon in foreground with verbose output
HR_QUIET=0 /usr/local/bin/hermes-route-daemon

# Or run reconcile with debug
HR_QUIET=0 HR_DIFF_MODE=check /usr/local/bin/agentic-route-reconcile
```

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

### GET /api/v1/status

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/api-reference.md

Returns the current routing status. This endpoint has no side effects.

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

### Description
Returns the current routing status. This endpoint has no side effects.

### Method
GET

### Endpoint
/api/v1/status

### Parameters
None

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

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

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

### GET /api/v1/check

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/api-reference.md

Performs drift detection and returns the number of drifted rules. This endpoint has no side effects.

```APIDOC
## GET /api/v1/check

### Description
Performs drift detection and returns the number of drifted rules. This endpoint has no side effects.

### Method
GET

### Endpoint
/api/v1/check

### Parameters
None

### Response
#### Success Response (200)
- **status** (string) - Always `ok`
- **drift** (number) - Number of drifted rules

#### Response Example
```json
{"status":"ok","drift":<n>}
```
```

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

### routes.json spec example

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/configuration.md

Full declarative desired rule set for routes.json. Includes rules, forbidden_rules, and pinned_routes. Used when you want to own every rule and route yourself.

```json
{
  "version": 1,
  "rules": [
    { "prio": 1000, "selector": "from all fwmark 0x80000/0xff0000", "action": "lookup main" }
  ],
  "forbidden_rules": [
    { "prio": 31580, "match": "suppress_prefixlength 0", "reason": "..." },
    { "match": "100.64.0.0/10 lookup main", "reason": "..." }
  ],
  "pinned_routes": [
    { "dst": "default", "via": "192.0.2.1", "dev": "eth0", "reason": "..." }
  ]
}
```

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

### GET /api/v1/enforce

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

Enforces the desired rules/routes. Returns a JSON object with an 'enforced' boolean set to true.

```bash
curl http://localhost:8099/api/v1/enforce
```

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

### GET /api/v1/status

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

Returns the full status of the agentic route service, including the live status and desired rules/routes.

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

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

### Force reconcile or restart daemon after VPN reconnect

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

If the daemon does not catch routing changes via ip monitor, force a reconcile with 'agentic-route enforce' or restart the daemon with systemctl.

```bash
# Force reconcile
agentic-route enforce

# Or restart daemon
systemctl restart agentic-route-daemon
```

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

### agentic-route mcp

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/cli-reference.md

Starts the stdio MCP JSON-RPC server for AI agent integration. It is read-only and exposes tools for status, drift detection, diff, and trace operations.

```APIDOC
## agentic-route mcp

### Description
Starts the stdio MCP JSON-RPC server for AI agent integration. It is read-only and exposes tools for status, drift detection, diff, and trace operations.

### Method
CLI command

### Endpoint
`agentic-route mcp`

### Parameters
None

### Tools Exposed
- `route_status` — desired vs live rules/routes plus drift count
- `route_check` — drift detection, no mutation
- `route_diff` — would-add / would-del / would-replace, no mutation
- `route_trace` — `ip route get <target> [from <src>]`

### Methods
`initialize`, `ping`, `tools/list`, `tools/call`

### Configuration
Reads `AGENTIC_ROUTE_CONF` (default `/etc/agentic-route/routes.json`).

### Request Example
```bash
agentic-route mcp
```

### Response
No specific response details provided.
```

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

### agentic-route api

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/cli-reference.md

Starts the mTLS REST API on the configured port. Requires socat with OpenSSL and a client certificate signed by the specified CA.

```APIDOC
## agentic-route api

### Description
Starts the mTLS REST API on the configured port. Requires socat with OpenSSL and a client certificate signed by the specified CA.

### Method
CLI command

### Endpoint
`agentic-route api`

### Parameters
None

### Configuration
- `AGENTIC_ROUTE_API_PORT` (default 8099)
- `AGENTIC_ROUTE_TLS_CA` — CA certificate for client certificate verification

### Request Example
```bash
agentic-route api
```

### Response
No specific response details provided.
```

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

### REST API status request

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/api-reference.md

Example curl command to query the REST API status endpoint. Uses client certificate and CA for mTLS.

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

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

### GET /api/v1/enforce

Source: https://github.com/dedsecorg/agentic-route/blob/master/wiki/REST-API.md

Applies reconciliation to enforce the desired state. Returns a JSON object with a boolean field 'enforced' set to true upon successful enforcement.

```APIDOC
## GET /api/v1/enforce

### Description
Applies reconciliation to enforce the desired state.

### Method
GET

### Endpoint
/api/v1/enforce

### Response
#### Success Response (200)
- **enforced** (boolean) - Always true when enforcement succeeds

#### Response Example
{
  "enforced": true
}
```

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

### GET /api/v1/diff

Source: https://github.com/dedsecorg/agentic-route/blob/master/wiki/REST-API.md

Returns a precise diff of the current state versus the desired state, similar to the CLI 'diff' command. This endpoint provides detailed information about discrepancies.

```APIDOC
## GET /api/v1/diff

### Description
Returns a precise diff of the current state versus the desired state, similar to the CLI 'diff' command.

### Method
GET

### Endpoint
/api/v1/diff

### Response
#### Success Response (200)
- **diff** (object) - The diff details (structure not specified in source)

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

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

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

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/pki.md

Run as root on the host that owns the services. Use a short-lived CA key (kept offline if possible) and a per-service server cert. The script creates a CA (10 years), one server cert per service (1 year) with SANs covering how clients dial it, and one client cert per agent (90 days). For client certs, always pass an extfile because rustls (webpki) rejects X.509 v1 certificates, and `openssl x509 -req` emits v1 unless extensions are present. Keys are PKCS#8 PEM (`openssl req -newkey` default); the Rust loader accepts PKCS#8, SEC1 and PKCS#1.

```bash
umask 077
install -d -m 0700 /etc/agentic-route/certs /etc/agentic-route/certs/clients
cd /etc/agentic-route/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; do
  openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
    -subj "/CN=agentic-route-$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')

```

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

### Edit Intent File

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

Edit the intent file to add new routing rules or VPNs. The daemon auto-applies within 200ms without restart.

```bash
# Edit the intent file
vim /etc/agentic-route/intent.json
```

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

### Audit commands for verifying security hardening

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

Commands to verify the daemon's capabilities, systemd hardening settings, and file permissions. The getcap command should output '=ep cap_net_admin+ep'.

```bash
# Verify capabilities
getcap /usr/local/bin/agentic-route-daemon
# Should show: =ep cap_net_admin+ep

# Verify systemd hardening
systemctl show agentic-route-daemon --property=CapabilityBoundingSet,AmbientCapabilities,ProtectSystem,ReadWritePaths,NoNewPrivileges

# Verify file permissions
ls -la /usr/local/bin/agentic-route* /usr/local/lib/agentic-route/
ls -la /etc/agentic-route/
ls -la /run/agentic-route/
```

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

### Build Docker Image Locally

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/container.md

Build the agentic-route Docker image locally with the tag 'agentic-route'.

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

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

### Run Container Commands

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/container.md

Run the container with NET_ADMIN capability and host network. Use 'status' to query status, 'reconcile' to run reconciliation, and 'daemon' to run the daemon with a mounted volume for the intent file and config.

```bash
# Query status
docker run --rm   --cap-add=NET_ADMIN   --network=host   ghcr.io/dedsecorg/agentic-route:v1 status

# Run reconciliation
docker run --rm   --cap-add=NET_ADMIN   --network=host   ghcr.io/dedsecorg/agentic-route:v1 reconcile

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

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

### Verify unauthenticated peer rejection

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/pki.md

Run this command to confirm that the server rejects unauthenticated peers. It expects a TLS handshake failure with exit code 56, meaning the handler never spawns.

```bash
curl --cacert ca.crt https://127.0.0.1:8099/api/v1/status; echo "rc=$?"
# expect: rc=56 (TLS handshake failure, handler never spawned)
```

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

### Context7 Widget Script in _layouts/default.html

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/github-pages.md

Adds the Context7 chat widget to all pages. Place this script in the custom layout file _layouts/default.html.

```html
<script src="https://context7.com/widget.js" data-library="/dedsecorg/agentic-route" data-color="#059669" data-position="bottom-right"></script>
```

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

### Multi-VPN Stack intent.json configuration

Source: https://github.com/dedsecorg/agentic-route/blob/master/README.md

Configuration file for managing routing conflicts between NordVPN, ProtonVPN, and Tailscale. Defines forbidden rules, pinned routes, and custom rules to control routing behavior.

```json
{
  "forbidden_rules": [
    { "prio": 31580, "match": "suppress_prefixlength 0", "reason": "Proton suppress-bypass" },
    { "prio": 31581, "match": "lookup 245447468", "reason": "Proton split-tunnel capture" },
    { "match": "100.64.0.0/10 lookup main", "reason": "Tailscale hijack prevention" }
  ],
  "pinned_routes": [
    { "dst": "194.126.177.6/32", "via": "185.170.112.1", "dev": "eth0" },
    { "dst": "10.2.0.1/32", "dev": "proton0" },
    { "dst": "default", "via": "185.170.112.1", "dev": "eth0" }
  ],
  "custom_rules": [
    { "prio": 480, "selector": "from all to 100.64.0.0/10", "action": "lookup 52" },
    { "prio": 32765, "selector": "not from all fwmark 0xe1f1", "action": "lookup 205" }
  ]
}
```

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

### Run agentic-route in agent sandboxes

Source: https://github.com/dedsecorg/agentic-route/blob/master/README.md

Run the agentic-route container with NET_ADMIN capability and host network namespace. Use the status command to query routing state, or the daemon command to run the reconciliation loop with a mounted configuration directory.

```bash
# Query routing state and status
docker run --rm \
  --cap-add=NET_ADMIN \
  --network=host \
  ghcr.io/dedsecorg/agentic-route:v1 status

# Run the reconciliation loop in daemon mode
docker run -d \
  --name agentic-route \
  --restart unless-stopped \
  --cap-add=NET_ADMIN \
  --network=host \
  -v /etc/hermes-route:/etc/hermes-route \
  ghcr.io/dedsecorg/agentic-route:v1 daemon
```

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

### agentic-route daemon command

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/cli-reference.md

Runs event-driven daemon that watches intent file for changes. Options: --interval <ms> (debounce interval, default 200ms) and --state-dir <path> (state directory, default /run/agentic-route).

```bash
agentic-route daemon
```

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

### Kubernetes Controller Pattern

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

Describes the core reconcile loop: observed kernel state plus intent, compute delta, apply surgical ip rule/route, emit status.

```text
Observed (kernel) + Intent (/etc/.../intent.json)
  -> Compute Delta
  -> Apply (surgical ip rule/route)
  -> Emit Status (/run/.../state.json)
```

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

### Bypass Failing Upstream

Source: https://github.com/dedsecorg/agentic-route/blob/master/skills/agentic-route/SKILL.md

Bypass a failing resolver and prioritize backup.

```bash
agentic-route bypass stubby unbound
```

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

### agentic-route status output

Source: https://github.com/dedsecorg/agentic-route/wiki/Commands

Shows desired vs live rules/routes and drift. Read-only, does not mutate kernel.

```bash
$ agentic-route status
agentic-route status
Spec: /etc/agentic-route/routes.json

--- Desired rules ---
  480: from all to 100.64.0.0/10 lookup 52
  32765: not from all fwmark 0xe1f1 lookup 205

--- Live IPv4 rules ---
  0: from all lookup local
  100: from 192.0.2.10 lookup wan
  480: from all to 100.64.0.0/10 lookup 52
  32765: not from all fwmark 0xe1f1 lookup 205
  32766: from all lookup main
  32767: from all lookup default

--- Desired pinned routes ---
  198.51.100.7/32 via 192.0.2.1 dev eth0
  default via 192.0.2.1 dev eth0

--- Live IPv4 routes ---
  default via 192.0.2.1 dev eth0
  198.51.100.7 via 192.0.2.1 dev eth0

--- Drift ---
agentic-route diff
Spec: /etc/agentic-route/routes.json

--- rules missing from live (would-add) ---
--- forbidden rules present (would-del) ---
--- pinned routes missing (would-replace) ---
(read-only: run 'agentic-route enforce' to apply)
```

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

### Local Validation Commands

Source: https://github.com/dedsecorg/agentic-route/blob/master/CONTRIBUTING.md

Run these commands to validate changes locally before submitting a pull request. The first checks bash syntax, the second runs the CLI tests, and the third performs a dry-run of the npm package.

```bash
bash -n bin/agentic-route
./tests/test_cli.sh
npm pack --dry-run
```

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

### curl with client certificate

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/pki.md

Use this command to authenticate to the agentic-route API with a client certificate. It specifies the CA certificate, client certificate, and key. The API is bound to 127.0.0.1:8099.

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

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

### MCP route_check

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/api-reference.md

Performs drift detection and returns a text indicating whether the system is in sync or drift is detected. This tool never mutates state and takes no arguments.

```APIDOC
## MCP Tool: route_check

### Description
Performs drift detection and returns a text indicating whether the system is in sync or drift is detected. This tool never mutates state and takes no arguments.

### Method
MCP tools/call

### Parameters
None

### Response
- **text** (string) - Either `in-sync: no drift` or `drift detected (run 'agentic-route diff' for detail)`
```

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

### Claude Desktop configuration for agentic-route

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

Adds the agentic-route MCP server to Claude Desktop's configuration. The server runs read-only; mutation is not exposed via MCP.

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

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

### View agentic-route logs with journalctl

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/systemd.md

Follow logs in real time or view logs from the last hour.

```bash
journalctl -u agentic-route -f
journalctl -u agentic-route --since "1 hour ago"
```

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

### route_status

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

Shows live and desired kernel rules and routes. This is a read-only tool that provides a status overview of the routing configuration.

```APIDOC
## Tool: route_status

### Description
Shows live and desired kernel rules and routes. This is a read-only tool that provides a status overview of the routing configuration.

### Input
- `{}` (object) - No parameters required.

### Output
Returns a text content block with the status information, including the spec path and desired rules.

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

Response:
```json
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"agentic-route status\nSpec: /etc/agentic-route/routes.json\n\n--- Desired rules ---\n  480: from all to 100.64.0.0/10 lookup 52\n..."}]}}
```
```

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

### Routing Intent Configuration in /etc/agentic-route/intent.json

Source: https://github.com/dedsecorg/agentic-route/blob/master/README.md

Defines user intent with forbidden rules to remove, pinned routes to ensure exist, and custom rules to add if missing. The daemon writes discovered state to /run/agentic-route/state.json.

```json
{
  "version": 1,
  "comment": "User intent only. Daemon writes discovered state to /run/agentic-route/state.json.",
  "forbidden_rules": [
    { "prio": 31580, "match": "suppress_prefixlength 0", "reason": "Remove VPN capture rule at this priority" },
    { "match": "100.64.0.0/10 lookup main", "reason": "Never let VPN redirect mesh CIDR through main table" }
  ],
  "pinned_routes": [
    { "dst": "198.51.100.7/32", "via": "192.0.2.1", "dev": "eth0", "reason": "Keep VPN endpoint reachable outside tunnel" },
    { "dst": "default", "via": "192.0.2.1", "dev": "eth0", "reason": "Bare-metal fallback egress" }
  ],
  "custom_rules": [
    { "prio": 480, "selector": "from all to 100.64.0.0/10", "action": "lookup 52" },
    { "prio": 32765, "selector": "not from all fwmark 0xe1f1", "action": "lookup 205" }
  ]
}
```

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

### Diagnose routing Connectivity Outage

Source: https://github.com/dedsecorg/agentic-route/blob/master/skills/agentic-route/SKILL.md

Run status, health, and trace commands to diagnose a routing connectivity outage.

```bash
agentic-route status
agentic-route health
agentic-route trace google.com
```

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

### agentic-route diff output

Source: https://github.com/dedsecorg/agentic-route/wiki/Commands

Precise read-only diff showing +add, -del, ~replace. Does not mutate kernel.

```bash
$ agentic-route diff
agentic-route diff
Spec: /etc/agentic-route/routes.json

--- rules missing from live (would-add) ---
  + 480  from all to 100.64.0.0/10 lookup 52

--- forbidden rules present (would-del) ---
  - 31581  from all lookup 245447468

--- pinned routes missing (would-replace) ---
  ~ 198.51.100.7/32 via 192.0.2.1 dev eth0
```

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

### agentic-route reconcile command

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/cli-reference.md

Runs one-shot reconciliation to align kernel state with intent.

```bash
agentic-route reconcile
```

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

### agentic-route daemon

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/cli-reference.md

Runs an event-driven daemon that watches the intent file for changes and applies them. It supports options for debounce interval and state directory.

```APIDOC
## agentic-route daemon

### Description
Runs an event-driven daemon that watches the intent file for changes and applies them. It supports options for debounce interval and state directory.

### Method
CLI command

### Endpoint
`agentic-route daemon`

### Parameters
#### Options
- `--interval <ms>` — debounce interval (default: 200ms)
- `--state-dir <path>` — state directory (default: /run/agentic-route)

### Request Example
```bash
agentic-route daemon
```

### Response
No specific response details provided.
```

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

### route_diff

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

Provides a precise diff of spec vs live: rules to add, forbidden rules to remove, pinned routes to replace. This is a read-only tool that outputs the differences.

```APIDOC
## Tool: route_diff

### Description
Provides a precise diff of spec vs live: rules to add, forbidden rules to remove, pinned routes to replace. This is a read-only tool that outputs the differences.

### Input
- `{}` (object) - No parameters required.

### Output
Returns a text content block with the diff details.

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

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

### MCP route_diff

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/api-reference.md

Provides a precise would-add / would-del / would-replace listing of routing changes. This tool never mutates state and takes no arguments.

```APIDOC
## MCP Tool: route_diff

### Description
Provides a precise would-add / would-del / would-replace listing of routing changes. This tool never mutates state and takes no arguments.

### Method
MCP tools/call

### Parameters
None

### Response
- **text** (string) - The diff output
```

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

### route_trace

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

Traces how a packet to a target IP would route, optionally from a source IP. This is a read-only tool that provides routing trace information.

```APIDOC
## Tool: route_trace

### Description
Traces how a packet to a target IP would route, optionally from a source IP. This is a read-only tool that provides routing trace information.

### Input
- `target` (string) - Required - The target IP address to trace.
- `source` (string) - Optional - The source IP address to trace from.

### Output
Returns a text content block with the trace information.

### Example
```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"route_trace","arguments":{"target":"8.8.8.8","source":"192.0.2.10"}}}
```
```

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

### Pull agentic-route Docker images

Source: https://github.com/dedsecorg/agentic-route/blob/master/README.md

Pull the agentic-route container image from GHCR. Use the pinned release for deterministic CI/sandboxes, the moving major release for non-breaking fixes, or the latest build from the default branch.

```bash
# Pinned release (recommended for deterministic CI / sandboxes)
docker pull ghcr.io/dedsecorg/agentic-route:1.0.0

# Moving major release (auto-receives non-breaking fixes)
docker pull ghcr.io/dedsecorg/agentic-route:v1

# Latest build from default branch
docker pull ghcr.io/dedsecorg/agentic-route:latest
```

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

### agentic-route status

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/cli-reference.md

Shows the current routing state including policy rules, routes, and drift detection results. It compares desired rules from the intent file with live IPv4 rules from the kernel.

```APIDOC
## agentic-route status

### Description
Shows the current routing state including policy rules, routes, and drift detection results. It compares desired rules from the intent file with live IPv4 rules from the kernel.

### Method
CLI command

### Endpoint
`agentic-route status`

### Parameters
None

### Request Example
```bash
agentic-route status
```

### Response
#### Success Response
Output includes:
- Desired rules from intent file
- Live IPv4 rules from kernel
- Desired pinned routes
- Live IPv4 routes
- Drift detection results
```

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

### agentic-route reconcile

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/cli-reference.md

Runs a one-shot reconciliation to align kernel state with the intent file. This is a CLI/operator action that mutates kernel state.

```APIDOC
## agentic-route reconcile

### Description
Runs a one-shot reconciliation to align kernel state with the intent file. This is a CLI/operator action that mutates kernel state.

### Method
CLI command

### Endpoint
`agentic-route reconcile`

### Parameters
None

### Request Example
```bash
agentic-route reconcile
```

### Response
No specific response details provided.
```

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

### MCP route_status

Source: https://github.com/dedsecorg/agentic-route/blob/master/docs/api-reference.md

Returns the desired spec versus live IPv4 rules/routes plus drift count. This tool is read-only and takes no arguments.

```APIDOC
## MCP Tool: route_status

### Description
Returns the desired spec versus live IPv4 rules/routes plus drift count. This tool is read-only and takes no arguments.

### Method
MCP tools/call

### Parameters
None

### Response
- **text** (string) - The status output
- **drift** (number) - Drift count
```
Tokens:
Raw