NAVIGATOR: one front door for agents on real networks
An AI agent should be able to read any device, propose a change and help troubleshoot,
without ever holding a password and without being able to change a device on its own. NAVIGATOR is
one MCP server that does this, built in three layers: ATLAS knows what you own, RUDDER talks to
the devices, NAVIGATOR runs the engineer's workflow.
1 MCP server for the agent16 tools9 engineer roles10 vendor packs174 platforms in the catalogue324 tests
The agent sees one server. Everything below the front-door check is code the model cannot reach
directly: no inventory file, no key, no device session, and no way to approve a change.
Why a front door
Each network-device MCP server today has its own inventory format, reads its password from its own
environment variable, and has its own idea of approval, often a field the model fills in itself.
Giving an agent several such servers side by side means every safety rule has to be repeated in every
server, and one forgotten rule is a way around all the others.
NAVIGATOR puts one check in front of everything. Every call that touches an inventory, a device or a
change passes these steps before any layer below sees it:
Which job. The call names a project (or ad hoc work). Output is written to that project's
records, and a line goes to its run log.
Which mode. A LOCKED project works only on its own inventory, keeps its data
local and refuses specific web searches. OPEN projects may use cloud models.
Which inventory. Each agent has an allow list of inventories and credential tags.
Credentials are always tags; the value never appears.
Which commands. Reads run only if the command is on the platform's allowlist.
Writes. Only as a change ticket that a person approves outside the chat.
The three layers
Layer 1
ATLAS
What you own, and how to log in
Devices, controllers (SD-WAN Manager, Panorama, Meraki …) and out-of-band gear.
Platform catalogue generated from netmiko, with each tool's name for the platform.
Credentials encrypted at rest (AES-256-GCM), bound to their tag.
A guided interview for every change: preview, your yes, commit, versioned.
Renders pyATS testbeds and Ansible, ANTA and multivendor inventories with
%ENV{…} references, never passwords. Exports to NetBox.
Layer 2
RUDDER
One way to every device
Native adapters where structured output or a safe commit path matters.
Everything else delegated to existing open-source MCP servers, behind the same rules.
Pick the connection method per call (via=pyats), compare two side by side,
get the raw text or the connection log.
Projects, OPEN or LOCKED, with task file, run log and records.
Nine roles as briefs for subagents, from data collection to SANITY_AGENT's QC.
A scrambler that removes secrets (or also IPs, ASNs, names) before anything goes to a public model.
Web research through self-hosted SearXNG: free, no API key, every query logged.
Uses the host agent's model; no model of its own. The chat model is CLOUD or LOCAL
(on Hermes per thread: /model cloud, /model local; default LOCAL).
Roles and vendor packs
By job: nine roles (sub-agents). The lead hands work to DATA_COLLECT, STATE_VALIDATOR,
LOG_REVIEWER, ANALYZER, CONFIG_GENERATOR, CONFIG_PUSH, DOCUMENTOR and SHIP_ENGINEER; every result passes the
SANITY_AGENT (QC) before the user sees it.
By vendor: ten vendor packs, one folder each, plugged into all three layers: platforms,
commands, interview fields and template examples for ATLAS; methods and adapters for RUDDER; knowledge for
the roles. Arista (eAPI, SSH), Cisco (pyATS, SSH, writer, SD-WAN Manager API and SSH), Palo Alto (SSH,
XML API reads and changes), Fortinet and multivendor (delegated MCP servers), Juniper / Aruba / F5 /
Check Point (servers not installed yet), and the generic netmiko fallback.
How a change happens
There is no approve tool. The approval code goes to a person on a separate channel and never into the chat,
so neither the model nor anything it reads can approve a change.
Propose → a person approves → apply
The agent calls change action=propose with the devices and config lines. RUDDER checks
the lines against a deny list, refuses production devices, locks the devices and makes a dry-run diff.
The person gets the devices, the diff, a link to a read-only change page (HTTPS) and a one-time code on
Telegram or Slack, or on any platform the host has (its own /pushok handler calls
rudder-approve). The code is bound to the exact devices, lines and config hash. A line the
device refused earlier is shown as not in this change, never dropped silently.
They answer /pushok CODE there. RUDDER then applies it by itself: drift check, commit with
the device's own rollback timer, verify, confirm or roll back. One result goes to the approval channel and
one to the chat thread; results a model types itself are removed.
Finished tickets and their pages are kept 90 days and cleaned up daily at 02:00; the audit log is never
trimmed. A ticket cut off by a crash is marked interrupted and reported, never retried.
Scheduled changes (“apply at 02:00”) are approved in advance. Thirty seconds before the start the person
gets a notice with a stop code; no answer means it runs.
SHIP_ENGINEER: troubleshooting the automation itself
The ninth role keeps the inventories and connections working. An engineer can jump in, run one command,
see exactly what the device returned and how, and compare connection methods, all read-only and recorded
in the project.
Say in chat
What runs
“show version on R1 via pyats”
device action=read via=pyats: that call only; nothing is stored
“compare R1 via ssh and pyats”
device action=compare: both outputs, time, errors and a per-command diff
“…with the debug log”
debug=true: the connection log, credential values removed
“use pyats for IOS-XE from now on”
adapter action=default: an interview preview; stored only after your yes
“give me an ANTA inventory for the fabric”
inventory action=render format=anta: one file per credential tag, no credentials
“start troubleshooting: pyATS reads time out”
troubleshoot action=start: every read until stop goes into one record
A real case: pyATS on an SD-WAN cEdge
pyATS reads of a lab Catalyst SD-WAN edge always timed out, while SSH read the same
device in under two seconds. One compare with debug=true showed the cause
inside pyATS's login library (unicon) for a Controller-Managed IOS-XE device:
+0.0 s connect with the generic IOS-XE plugin, log in
+2.9 s show version | include operating mode → Controller-Managed
pnpa service discovery stop ← sent to the device during a "read"
+10.4 s learn device tokens, redirect to the iosxe/sdwan plugin
+10.8 s wait for the console to settle
+21.8 s log in again
+24.8 s connected; the command gets the 5 s left of a 30 s budget
unicon's default login also enters config mode (no logging console,
line console 0, exec-timeout 0), so on a normal IOS-XE device a pyATS read quietly
changes the configuration. RUDDER now gives pyATS a connection that never enters config mode during a read,
skips the controller-mode probe for IOS-XE, keeps one login per run and gives pyATS its own timeout.
Before
~30 s / command
timed out
After
8.9 s / 3 commands
one ~3 s login, parsed JSON
For anyone building on pyATS: its default IOS-XE login changes device state
(pnpa service discovery stop on a cEdge, console settings everywhere), and every read-only tool
built on it inherits that.
The tools an agent sees
Tool
Actions
For
inventory
list show query validate history platforms commands template render netbox_export
ATLAS reads and rendered files
inventory_edit
start answer status preview commit cancel list
the interview
credential
list test
tags and login tests, never values
device
read facts compare
allowlisted reads, any connection method
adapter
list default
which method serves what; stored defaults
change
propose schedule status apply cancel list
tickets, approved out of band
troubleshoot
start note stop show
recorded sessions
project, mode
create show list status close task · get set
jobs, OPEN / LOCKED
role, qc, lesson, skill
list brief · check record · add list · list load
the 9 roles and their checks
scrambler, research
sanitize text restore map · query fetch
public-model safety, web search
local_model
status ask
a local model reads LOCKED files; the answer stays in the project
Running it
One shell command, navigator-setup, asks everything once and changes it later. It is never a
chat tool, so an agent cannot redirect approvals or open the server to itself.
Part
How it works
Setup interview
Project and skill folders, approvals (and rudder-approve for other hosts), page retention, the cloud or local model, HTTPS, the recovery key and a first backup. Every value is checked before it is saved.
Remote clients
HTTPS on 8791 (ATLAS 8792, RUDDER 8793) with a certificate from a CA made on the host. Users are admin or engineer, with a random password made by NAVIGATOR. Engineers cannot commit inventory changes.
Change pages
HTTPS on 8790 with the same CA. A random link per ticket, read-only, kept 90 days.
Credentials key
32 random bytes, so atlas-link runs unattended. A 48-digit recovery key (BitLocker style, shown once) opens a sealed copy of it.
Backup and restore
One encrypted file of every setting, key, inventory and state. Made only after the recovery key is typed and checked; restored with the file and the recovery key alone, also on a new host.
Models
The host's own model does the thinking: CLOUD or LOCAL. On Hermes each thread picks it with /model cloud or /model local (default LOCAL when a local model is set), and asking for a LOCKED project switches the thread to LOCAL. On a cloud model, LOCKED project data is read only by the local one (local_model); navigator-guard blocks the host's own tools on it. navigator-setup asks for the local endpoint and model and checks them.
The rules
The agent talks to NAVIGATOR only; each layer calls only the one below it.
Passwords never reach a model: tags in every reply, references in every rendered file.
ATLAS and RUDDER are plain Python with no AI model inside.
Every device change is a ticket a person approves with /pushok outside the chat.
A read never changes a device, including through the libraries underneath.
No host-specific code: the same server runs over stdio, SSH or HTTPS with a login, under Hermes, OpenClaw, Claude Code or Cursor.
builtRUDDER: reads (native and delegated), Arista, Cisco and PAN-OS changes, scheduled changes, compare and debug
builtNAVIGATOR: projects, 9 roles, QC, scrambler, SearXNG research, the single front door, navigator-setup, ten vendor packs, local and cloud models (local_model)
builtApprovals for any host (rudder-approve, set up by navigator-setup), change pages with 90-day retention, one result per ticket
builtHTTPS with logins for the three MCP servers (8791–8793) and the change pages (8790), from a local CA
builtA recovery key for the credentials key; one-file encrypted backup and restore
liveRunning for a Hermes agent on Slack against lab fabrics; from Claude Code over SSH or HTTPS; Ollama on the same host for LOCKED files
nextTeams approvals, pack fields in the interview, Cisco NETCONF / RESTCONF and IOS-XR changes, encrypted secrets in host configs (Bitwarden is an option), pip / uv packaging
packagingOne navigator-mcp server; atlas-mcp (inventory) and rudder-mcp (devices) also run on their own