Skip to content

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:

  1. a way to reach navigator-mcp (stdio on the same machine, stdio over SSH, or HTTPS with a login on 8791, HTTPS.md);
  2. the settings file (NAVIGATOR_BOOTSTRAP, made by navigator-setup, see INTERVIEW.md);
  3. an approval path a person uses outside the chat: the Hermes approval bot, or the host's own /pushok handler calling rudder-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's SOUL.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 in APPROVAL.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 .env or 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 the push-approve plugin (integrations/hermes/push-approve/). Never the chat profile: the bot that asks must not be able to approve. Set it with navigator-setup (APPROVAL.BOT).
  • Restart after changes: systemctl --user restart hermes-gateway (move the profile's cache/mcp_schema_cache.json aside when the tool list changed), then /mcp in 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 default model: so threads start local; NAVIGATOR's local_model works 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