hermes-cortex-setup

name	hermes-cortex-setup
version	1.0.0
description	Install and configure Hermes Cortex core components — Ollama, mycortex knowledge brain, health server, agent registry, hooks, cron jobs, and profile scaffolding on a target machine.
behavioral_principles	["The knowledge brain is mycortex — install it via the repo's cortex-update.sh (register-based deploy), never via pip/npm/bun. The legacy brain is decommissioned 2026-08-02; do not install or restart it.","When installing Bun, prefer download-inspect-execute over raw curl|bash when the security scanner flags it.","Always create a .env file in ~/hermes-cortex/ before running install-orch-crons.sh to avoid silent failure.","When sudo is unavailable, install Ollama from GitHub releases tarballs (not the official install.sh which requires root).","Before writing custom configs or inventing new approaches, check the repo's docs/ and ops/scripts/ first for existing documented solutions. Use the documented tools as primary; custom workarounds are a last resort.",{"When setting up services on a target machine, inspect running configs FIRST — check /etc/nginx/sites-enabled/, systemctl --user …":"(1) running machine configs, (2) hermes-cortex repo docs/, (3) agent-registry.template.json."},"For systemd user services that run bun scripts, always set explicit PATH in Environment= — systemd does not inherit the user shell's PATH.","Verify each install step with a version check or doctor command before proceeding to the next.","After installing components, update PATH persistence in shell config (~/.bashrc) for Bun and ~/.local/bin.","The canonical SOUL.md path is ~/.hermes/SOUL.md — never write to /home/<other-user>/ paths without verifying they exist.","The brain directory structure needs git-init'd MECE subdirectories (19 dirs), not just flat kb/memories dirs.","The health-vector.py server binds to 127.0.0.1 by default; nginx proxies external traffic. No need to patch bind addresses — health-vector.py has zero pip dependencies and no EXTERNAL_HEALTH_URL requirement.","Register brain sources with the mycortex CLI: `mycortex sources add <name> <path>` then `mycortex sync --source <name>`. mycortex is Python — no bun, no daemon, no PGLite lock contention.","When the user gives a cross-user path for SOUL.md (e.g. ~/...), redirect to ~/.hermes/SOUL.md and inform them — never create files in another user's home.","The user prefers the short /health endpoint path for external health URLs, not /api/v1/health. The former returns a compact vector, the latter returns full JSON. Always default to /health unless the user specifies otherwise.",{"The health server exposes two endpoints with different response formats":"/health (compact 9-element vector, ideal for orchestrator polling) and /api/v1/health (full JSON, ideal for debugging). When configuring EXTERNAL_HEALTH_URL, use /health per user preference."},"mycortex sync is a 15-min cron (agent-mycortex-sync); there is no sync daemon to stop. After `sources add`, run `mycortex sync --source <name>` manually to index immediately.","When setting up an agent on a target machine, always check the machine's existing deployed configs FIRST — especially /etc/nginx/sites-enabled/ and /etc/systemd/system/ and /etc/nginx/conf.d/. The actual upstream port definitions may differ from what the docs say. Check nginx configs for upstream blocks before choosing internal ports.",{"Before writing custom configs or inventing port schemes, check three sources in order":"(1) the running config on the machine itself (nginx sites-enabled, systemd services), (2) the hermes-cortex repo docs/ directory, (3) the agent-registry.template.json. Only after exhausting these three should you write a custom approach."},"mycortex has no daemon and no PGLite lock — sources are synced via the mycortex CLI/cron. Never install the legacy brain or its services; the doctor treats leftover legacy units as stale.","fail2ban, nginx config deployment, and apt package installation require sudo. When these steps are needed and sudo is unavailable, prepare config files at `~/.hermes-cortex/nginx/` and scripts at `~/.hermes-cortex/scripts/` with full terminal commands printed for the user to copy-paste. Never assume sudo is available.","The health-vector.py service must run on port 8905 (127.0.0.1). This is what the deployed nginx `upstream health_backend` block expects. Do not change the port unless the nginx config explicitly defines a different upstream.","After the `src/` → `ops/` repo migration (July 2026), many deployed scripts retained stale `src/` paths. When fixing a script that references `src/scripts/` or `src/loop-governance/`, check if the file moved to `ops/scripts/` or `runtime/loop-governance/`. The old `src/` tree was completely removed. Grep for `src/` references in any script you patch as a matter of course.","Bus on 8903, health-vector on 8905. Never conflate them. The bus ExecStart must use the Hermes venv python (has uvicorn), not /usr/bin/python3.","Name the bus service file cortex-bus.service, not cortex-bus.service. The doctor checks for exactly cortex-bus.service.",{"Verify bus setup at three layers":"(1) systemctl is-active cortex-bus.service, (2) curl :8903/health returns backend pgmq, (3) nginx upstream cortex_bus_backend matches :8903. A running process on a port is not enough."},"After cortex-update , check ~/.hermes/scripts/ for symlinks that point outside the scripts dir. Cron's no_agent runtime rejects symlinks. Replace with real `cp` copies.","no_agent cron scripts don't inherit Hermes env vars. If a script needs CORTEX_BUS_TOKEN or CORTEX_BUS_URL, ensure they're set via ~/.hermes-cortex/cortex-bus.conf, not just ~/hermes-cortex/.env.","After running install-orch-crons.sh, always check for stale old-name duplicate crons (bus-* vs orch-bus-*) and remove them. The installer doesn't auto-uninstall renamed crons.","When patching a no_agent cron script that uses `docker`, always wrap with `sg docker -c`. The cron runtime doesn't have docker group access even if the agent's shell does.","After cortex-update , verify deployed cron scripts in ~/.hermes/scripts/ are real file copies, not symlinks to the repo. Cron runtime rejects symlinks that resolve outside ~/.hermes/scripts/.","When running cortex-update.sh from its deployed location at ~/.hermes/scripts/, always export REPO_DIR=$HOME/hermes-cortex first. The script auto-detects REPO_DIR from $(dirname \"${BASH_SOURCE[0]}\") which resolves to ~/.hermes/scripts/ — not a git repo — and fails with \"✗ Not a git repository\"."]
trigger	User asks to install, set up, deploy, or bootstrap Hermes Cortex, or mentions 'cortex setup', 'install cortex', 'hermes-cortex components'. The cron health report shows an agent as 🔴 unreachable — the fix is often missing health server + agent registry on that machine.

Hermes Cortex Setup

Walkthrough for installing the core Hermes Cortex components on a Linux (or macOS) machine. Each step is verified before moving to the next.

Prerequisites

• Linux or macOS host
• curl, git, python3, unzip available
• Hermes Agent installed (the cortex skill set layers on top)
• Target repo cloned: git clone https://github.com/nousresearch/hermes-cortex.git ~/hermes-cortex

Installation Steps

0. Prerequisites Check

# Check what's available
echo "Python: $(python3 --version 2>/dev/null || echo 'MISSING')"
echo "Git: $(git --version 2>/dev/null || echo 'MISSING')"
echo "Docker: $(docker --version 2>/dev/null || echo 'MISSING')"
echo "Sudo: $(sudo -n echo 'yes' 2>/dev/null || echo 'no')"
echo "Python3.12: $(python3.12 --version 2>/dev/null || echo 'MISSING')"

Pitfall — Hermes venv vs system Python: pip packages are installed in ~/.hermes/hermes-agent/venv/. The python3 on PATH is usually this venv's python. Use /usr/bin/python3 for system stuff and ~/.hermes/hermes-agent/venv/bin/python3 for agent-dependent services.

0.5. Clone the Repo (if not already cloned)

git clone --depth 1 https://github.com/fleet-operator/hermes-cortex.git ~/hermes-cortex

Pitfall — Installer script path bug: The install.sh script references scripts at $(_scripts)/install-ollama.sh but the actual file is at $(_scripts)/install/install-ollama.sh (inside an install/ subdirectory). Running install.sh directly will fail on step 1 with a "No such file or directory" error. Fix: run the individual install scripts manually rather than the monolithic installer, or symlink the paths.