The first-time setup, and changing it later¶
Two interviews set NAVIGATOR up. Both run on the host's shell, never as a chat tool: an agent that could change where approvals go, or read a password, could get around every other rule.
| Interview | Command | Sets |
|---|---|---|
| Host settings | navigator-setup |
PROJECT_ROOT, SKILLS_ROOT, approvals, retention |
| Inventories and credentials | atlas-interview (on the host) or inventory_edit (in chat, no secrets) |
devices, controllers, credential tags, who may use what |
| Models | navigator-setup → MODELS in navigator.yml |
cloud or local host model, the local endpoint |
Order the first time: install (INTEGRATION.md §0) → navigator-setup → inventory →
credentials → services → connect the host → a test read → a test change.
1. navigator-setup (host settings)¶
navigator-setup # asks every question; Enter keeps the value in [brackets]
navigator-setup show # what is set now
| Question | What to answer | Checked |
|---|---|---|
| PROJECT_ROOT (required) | the folder that holds project folders, data only (e.g. /data/projects) |
absolute, exists, readable and writable |
| SKILLS_ROOT (optional) | a folder of your own skills, one <skill>/SKILL.md each (e.g. /data/skills); - for none. NAVIGATOR only reads it |
absolute, readable, at least one skill |
| APPROVAL.METHOD | telegram or slack (Hermes approval bot), or another platform your host sends to (teams, discord…, its /pushok handler calls rudder-approve) |
one of the known methods |
| APPROVAL.BOT | the approval bot's Hermes profile, never the chat bot | the profile exists; not a REPLY_PROFILE |
| APPROVAL.CHANNEL | Slack: the private approval channel's ID (C…); Telegram: a chat ID or - for the bot's home channel |
an ID |
| APPROVAL.APPROVERS | * (anyone in the approval channel; you curate who is in it) or user IDs |
IDs |
| APPROVAL.SELF_APPROVE | may the person who asked approve their own change | true / false |
| APPROVAL.SHIP_ENGINEERS | user IDs whose lab changes need no approval (lab inventories only, still audited); - for none |
IDs, never * |
| APPROVAL.PAGES_KEEP_DAYS | days to keep finished tickets, their change pages and baseline records (default 90) | 1–3650 |
| APPROVAL.CLEANUP_AT | the daily clean-up time, local HH:MM (default 02:00), or off |
HH:MM |
When approvals change (METHOD, BOT, CHANNEL, APPROVERS, SELF_APPROVE, SHIP_ENGINEERS), a test code is sent
the new way and nothing is saved until someone approves it there. Every file is backed up first and every
change is logged in <STATE_PATH>/settings.log. Afterwards restart rudder-scheduler and the MCP host.
Not asked, set with navigator-setup set: APPROVAL.REPLY_PROFILES (chat bots that may post results in a
thread), APPROVAL.WEB_BIND / WEB_URL (change pages on TCP 8790), APPROVAL.TTL_MIN (minutes a ticket
may wait), APPROVAL.MENTION.
2. Inventories¶
On the host (atlas-interview run <topic>) or from the chat (inventory_edit, the same questions). Every
change goes: questions → your answers → preview → your yes → commit; every version is kept
(atlas-interview history <inventory>).
| Topic | For |
|---|---|
inventory_new |
a new inventory (name, lab or production, default credential tag) |
record_add / record_edit / record_remove |
one device, controller or out-of-band record |
bulk_import |
many records from a CSV / YAML you have |
bulk_edit |
one field on many records (e.g. ADAPTER=pyats on all IOS-XE) |
credential_new |
a credential tag (the value is set separately, below) |
consumer_access |
host only: which agent (consumer) may use which inventories and tags |
"Give me the inventory template" (in chat) shows one example record per vendor and connection method. A
record needs at least DEVICE_NAME, OS (a platform from the catalogue: "which platforms do you support?"),
the management address, the connection type and a credential tag. Mark production devices PRODUCTION: true:
changes to them are refused unless the host allows it.
3. Credentials¶
Passwords are never typed in a chat. After credential_new (or a record that needs a secret), on the host:
atlas-interview secret <draft> LOGIN_PASSWORD # asked with getpass, or --file
atlas-interview secret <draft> ENABLE_SECRET
Then, in chat: "test the login on LEAF1A" (credential action=test: login + show version, no secret
shown). The vault is encrypted (AES-256-GCM); only atlas-link holds the key (ATLAS.md).
rudder-approve (hosts other than Hermes)¶
After the approval questions, the interview asks whether a host other than Hermes' push-approve plugin
(OpenClaw, a Teams or Discord bot…) records !pushok with rudder-approve. The default is yes when
APPROVAL.METHOD is not telegram or slack. Then it asks:
| Question | Answer (default from the APPROVAL settings) |
|---|---|
APPROVE.PLATFORMS |
where approvals may come from, e.g. teams |
APPROVE.CHANNELS |
platform=ID pairs, e.g. teams=19:abc@thread.tacv2; - = any channel |
APPROVE.APPROVERS |
* or user IDs |
It writes ~/.config/rudder/approve.yml (APPROVALS.md section 13).
4. Models: cloud and local¶
The interview asks three questions after the approvals (LOCAL_MODELS.md):
| Question | Answer |
|---|---|
MODELS.HOST |
the model your MCP host itself runs: cloud (Claude, Gemini, GPT…) or local (Ollama…) |
MODELS.LOCAL_URL |
a local OpenAI-compatible endpoint for LOCKED work, e.g. http://127.0.0.1:11434/v1; - for none |
MODELS.LOCAL_MODEL |
the model's name there, e.g. qwen3.5:9b |
Setup checks them before saving: the URL must be a local address (loopback, private, link-local), the
endpoint must answer, and it must have that model. Otherwise nothing is saved. HOST: local needs a
local URL. Later: navigator-setup set MODELS.LOCAL_MODEL qwen3:30b-a3b (also MODELS.HOST,
MODELS.LOCAL_URL, MODELS.TIMEOUT_SEC; MODELS.LOCAL_URL "" removes the local model).
They are saved in ~/.config/navigator/navigator.yml as:
MODELS:
HOST: cloud # what your host's model is: cloud | local
LOCAL: {URL: "http://127.0.0.1:11434/v1", MODEL: "qwen3.5:9b"}
- Cloud model (Gemini on Vertex, Claude, OpenAI…): configured in the host (Hermes profile model, Claude Code login). NAVIGATOR never calls it itself and stores no key for it.
- Local model (Ollama, vLLM, LM Studio, llama.cpp): an OpenAI-compatible URL on a local address. Check with "local model status" in chat.
- A host on the local model sets
NAVIGATOR_HOST_MODEL=localin its MCP config; then LOCKED files may be read directly. MODELS.HOSTis not the chat model. On Hermes each thread picks its own with/model cloudor/model local(default LOCAL when the profile has a local model); the interview does not set that. See LOCAL_MODELS.md.
4b. HTTPS for remote clients (optional)¶
The interview's last question: let MCP clients on other machines connect over HTTPS with a login (ports 8791-8793)? yes makes the local CA, the server certificate and a first admin user, and prints that user's password once. Details, more users and connecting Claude Code / Cursor / Hermes: HTTPS.md.
4c. The recovery key and a first backup¶
Next the interview makes the recovery key of the CREDENTIALS key: 48 digits in 8 groups of 6, shown once. You type it back to confirm. If there is no CREDENTIALS key yet, it makes that too. Then it offers a first full encrypted backup. The backup asks for the recovery key again and checks it, so you know you hold the right one. See BACKUP.md.
5. Changing it later¶
| Change | How |
|---|---|
| any host setting | navigator-setup set KEY VALUE, add / remove for lists; or run the interview again |
| test the approval path | navigator-setup test-approval |
| recovery key, backup, restore | navigator-setup recovery init/check, navigator-setup backup, navigator-setup restore FILE (BACKUP.md) |
| HTTPS users and certificate | navigator-setup user add/reset/role/remove/list, navigator-setup tls init/renew/show, navigator-setup http show |
| an inventory or a record | chat: "add a device …" / "change the ADAPTER of EDGE1 to ssh" (preview, yes) |
| a password | host: atlas-interview secret …; then "test the login on …" |
| who may use an inventory | host: atlas-interview run consumer_access --consumer <NAME> |
| models | navigator-setup set MODELS.HOST local, MODELS.LOCAL_URL …, MODELS.LOCAL_MODEL …; then restart the MCP host |
| rudder-approve (non-Hermes hosts) | navigator-setup set APPROVE.PLATFORMS …, add APPROVE.CHANNELS platform=ID, add APPROVE.APPROVERS … (writes ~/.config/rudder/approve.yml, mode 600); rudder-approve check |
After any change: systemctl --user restart rudder-scheduler (and atlas-link after an inventory or pack
change), then restart or /reload-mcp the host.