Connecting NAVIGATOR to a host¶
NAVIGATOR is a plain MCP server. A host is the agent program that starts it and gives its tools to a model: Hermes, OpenClaw, NetClaw, Claude Code, Cursor, or your own. The host keeps its own chat connections (Slack, Telegram, Teams, Discord…); NAVIGATOR ships none. It only needs:
- a way to reach
navigator-mcp(stdio on the same machine, stdio over SSH, or HTTPS with a login on 8791, HTTPS.md); - the settings file (
NAVIGATOR_BOOTSTRAP, made bynavigator-setup, see INTERVIEW.md); - an approval path a person uses outside the chat: the Hermes approval bot, or the host's own
/pushokhandler callingrudder-approve(APPROVALS.md §13).
| Host | How it starts NAVIGATOR | Results in the chat thread | Approvals |
|---|---|---|---|
| Hermes (a profile) | stdio, mcp_servers in the profile's config.yaml |
yes (navigator-reply plugin) |
a separate Hermes approval profile (push-approve plugin) |
| NetClaw | the same as Hermes (NetClaw runs as a Hermes profile) | yes | the same |
| OpenClaw | stdio or HTTPS (8791, HTTPS.md) | no (ask for the status) | its own /pushok handler → rudder-approve |
| Claude Code | stdio, or stdio over SSH (.mcp.json) |
no | the approval channel (Slack / Telegram) |
| Cursor | the same as Claude Code (.cursor/mcp.json) |
no | the same |
Give the agent only navigator: not atlas-mcp or rudder-mcp beside it (they would skip the
front-door checks), and no shell access to ~/.config/atlas, ~/.rudder, the approval folder or the
inventories.
0. Install once per machine¶
A Python 3.11+ environment of its own. With pyenv, an environment named NAVIGATOR:
pyenv install 3.12 # if not there yet
pyenv virtualenv 3.12 NAVIGATOR
git clone <your copy of the navigator repo> ~/navigator
cd ~/navigator
pyenv local NAVIGATOR
pip install setuptools wheel
pip install --no-build-isolation -e ".[test]"
python -m pytest -q # no devices, no network
The commands are then in $(pyenv prefix NAVIGATOR)/bin/ (navigator-mcp, navigator-setup,
atlas-link, rudder-scheduler, rudder-approve, atlas-interview, atlas-vault). A plain
python3 -m venv ~/navigator/.venv works the same way; later this becomes pip install / uv tool install.
Then, on the host's shell (never from a chat):
navigator-setup # PROJECT_ROOT, SKILLS_ROOT, approvals, retention
atlas-interview run inventory_new ... # or import an inventory (INTERVIEW.md)
systemctl --user enable --now atlas-link rudder-scheduler
atlas-link holds the credential key; rudder-scheduler applies approved changes and serves the change
pages. Both are systemd user services (ATLAS.md, SCHEDULER.md).
1. Hermes: a profile named navigator¶
A dedicated profile keeps NAVIGATOR's chat bot apart from your personal bot.
hermes profile create navigator # its own config.yaml, SOUL.md, .env, sessions
In ~/.hermes/profiles/navigator/config.yaml:
mcp_servers:
navigator:
command: /home/<user>/.pyenv/versions/NAVIGATOR/bin/navigator-mcp
env:
NAVIGATOR_BOOTSTRAP: /home/<user>/.config/navigator/navigator.yml
NAVIGATOR_HOST_MODEL: cloud # or local, if this profile's model is local (LOCAL_MODELS.md)
connect_timeout: 60
enabled: true
plugins:
enabled:
- navigator-reply # results back in the thread; strips results the model types itself
display:
platforms:
slack: {show_reasoning: false, interim_assistant_messages: false, tool_progress: new}
- SOUL: start from
integrations/hermes/soul/chatbot-ChatBot-SOUL.md(copy to the profile'sSOUL.md, change the name). It holds the change rules: every requested item in the lines, never write a result yourself, never touch approvals. - Plugin: copy
integrations/hermes/navigator-reply/to~/.hermes/profiles/navigator/plugins/. RUDDER posts results only for profiles listed inAPPROVAL.REPLY_PROFILES:navigator-setup add APPROVAL.REPLY_PROFILES navigator. - Chat connection: the profile's own Slack app or Telegram bot, set up the Hermes way (its tokens in the
profile's
.envor your secret store). One Slack app per bot instance. - The approval bot is another profile (e.g.
navi) with no agent tools, its own Slack app or Telegram bot, and thepush-approveplugin (integrations/hermes/push-approve/). Never the chat profile: the bot that asks must not be able to approve. Set it withnavigator-setup(APPROVAL.BOT). - Restart after changes:
systemctl --user restart hermes-gateway(move the profile'scache/mcp_schema_cache.jsonaside when the tool list changed), then/mcpin the chat. - A local model: Hermes model aliases (
model_aliases: {cloud: …, local: {provider: custom, base_url: http://127.0.0.1:11434/v1}}) switch the thread's model with/model cloud//model local; make the local one the profile's defaultmodel:so threads start local; NAVIGATOR'slocal_modelworks either way (LOCAL_MODELS.md).
2. NetClaw¶
NetClaw runs as a Hermes profile, so the steps are those of section 1 in its profile: the navigator MCP
entry, the navigator-reply plugin, the change rules in its SOUL, and a separate approval profile. Keep
NetClaw's own device tools off for the inventories NAVIGATOR manages, so every device call goes through the
front door.
3. OpenClaw¶
Stdio on the same machine, in openclaw.json (the MCP section of your OpenClaw version):
{ "mcp": { "servers": { "navigator": {
"command": "/home/<user>/.pyenv/versions/NAVIGATOR/bin/navigator-mcp",
"env": { "NAVIGATOR_BOOTSTRAP": "/home/<user>/.config/navigator/navigator.yml",
"NAVIGATOR_CONSUMER": "LAB_BOT" } } } } }
Or over HTTPS for an agent on another machine: navigator-mcp --serve (systemd navigator-mcp-https, port
8791) with a user and password from navigator-setup user add (HTTPS.md). NAVIGATOR_CONSUMER picks
the inventories and credential tags this agent may use.
Approvals: point RUDDER at the platform OpenClaw listens on (navigator-setup set APPROVAL.METHOD slack
APPROVAL.CHANNEL <id>; the request is sent with the Hermes sender today) and let OpenClaw's own /pushok
command run rudder-approve ok CODE --user <sender id> --platform slack --channel <channel id> with the
identity from its message event. The config ~/.config/rudder/approve.yml is required.
4. Claude Code¶
Same machine: claude mcp add navigator --scope user -e NAVIGATOR_BOOTSTRAP=<path> -- <env>/bin/navigator-mcp.
Another machine: stdio through SSH, no port to open (CLAUDE_CODE.md; a ready
.mcp.json in examples/claude-code/):
{ "mcpServers": { "navigator": { "type": "stdio", "command": "ssh",
"args": ["-T", "-o", "BatchMode=yes", "navhost",
"NAVIGATOR_BOOTSTRAP=/home/<user>/.config/navigator/navigator.yml exec /home/<user>/.pyenv/versions/NAVIGATOR/bin/navigator-mcp 2>/dev/null"] } } }
/mcp must show navigator connected with 16 tools. Claude Code has no thread for RUDDER to post into:
approve in the approval channel, then ask for the ticket's status. It runs on a cloud model
(NAVIGATOR_HOST_MODEL stays cloud); LOCKED files are read by local_model.
5. Cursor¶
The same mcpServers block in .cursor/mcp.json (one project) or ~/.cursor/mcp.json (all), then
Settings → MCP. Everything else as Claude Code.
6. Your own host¶
Any MCP client works: start navigator-mcp (stdio) or connect to https://<host>:8791/mcp with a login (HTTPS.md). To post results
back in a thread, set reply_to on change action=propose from your host code, never from the model
(format <profile>/<platform>:<chat>[:<thread>]), and requested_by (<user id>|<name>) the same way.
For approvals, call rudder-approve from your /pushok handler.
Checklist¶
- [ ]
navigator-setup show: PROJECT_ROOT, approvals, retention as you want them. - [ ]
systemctl --user is-active atlas-link rudder-scheduler: both active. - [ ] The host lists 16 NAVIGATOR tools and no
atlas-mcp/rudder-mcp. - [ ] A read works: "show version on ".
- [ ] A test change on a lab loopback reaches the approval channel, and only a person can approve it.
- [ ]
navigator-setup test-approvalpasses for the approval method you chose.