hermes-cortex-setup

Files (2)

• SKILL.md
• llm-cron-model-fallback.md · references/

SKILL.md (first lines)

# 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

```bash
# 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)

```bash
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.

### 1. Install Ollama (Local LLM Server for Embeddings)

**No-sudo install (when sudo is unavailable):**

Ollama's official `install.sh` requires root to install to `/usr/local`. When sudo is unavailable, use the GitHub releases tarball:

```bash
# Detect the correct download URL (format changed to .tar.zst in v0.31+)
OLLAMA_VERSION="v0.31.2" # Latest stable as of Jul 2026
curl -fsSL --retry 3 --retry-delay 5 \
 -o /tmp/ollama-linux-amd64.tar.zst \
 "https://github.com/ollama/ollama/releases/download/${OLLAMA_VERSION}/ollama-linux-amd64.tar.zst"

# Extract
mkdir -p /tmp/ollama-extract
tar --zstd -xf /tmp/ollama-linux-amd64.tar.zst -C /tmp/ollama-extract/

# Install binary
mkdir -p ~/.local/bin
cp /tmp/ollama-extract/bin/ollama ~/.local/bin/ollama
chmod +x ~/.local/bin/ollama

# Install libraries (llama-server + .so backends)
mkdir -p ~/.local/lib/ollama
cp -r /tmp/ollama-extract/lib/ollama/* ~/.local/lib/ollama/
chmod +x ~/.local/lib/ollama/llama-server

# Verify
~/.local/bin/ollama --version
```

**Systemd user service:**

```bash
mkdir -p ~/.config/systemd/user/
cat > ~/.config/systemd/user/ollama.service << 'EOF'
[Unit]
Description=Ollama LLM Server
After=network-online.target

[Service]
ExecStart=%h/.local/bin/ollama serve
Environment=OLLAMA_HOST=127.0.0.1
Environment=OLLAMA_NUM_THREADS=2
Environment=OLLAMA_KEEP_ALIVE=0
Restart=on-failure
RestartSec=3

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable ollama.service
systemctl --user start ollama.service
```

**Pull the embedding model:**

```bash
ollama pull nomic-embed-text:v1.5
```

**Pitfall — tarball format change (July 2026):** Ollama changed their Linux release tarball format from `.tgz` (gzip) to `.tar.zst` (zstd) around v0.31.0. The old URL `https://ollama.com/download/ollama-linux-amd64.tgz` returns a 404. Always use the GitHub releases page at `https://github.com/ollama/ollama/releases` and download the `.tar.zst` variant. The herd-installer scripts that still reference `.tgz` will fail — fix by downloading from releases.

**Pitfall — port binding on fresh install:** Ollama binds to 127.0.0.1 by default on a manual install. This is correct for single-machine setups. If deploying as a server that other agents poll, you'd set `OLLAMA_HOST=0.0.0.0` — but this also opens your LLM server to the LAN. Use nginx basic auth in front for production.

### 2. Install Bun (JavaScript runtime)

**Pitfall — security scanner blocking curl|bash:** The official Bun install (`curl -fsSL https://bun.sh/install | bash`) may be flagged by security scanners. Use the download-inspect-execute pattern:

```bash
# Download the install script for safety inspection
curl -fsSL https://bun.sh/install -o /tmp/bun-install.sh

# Inspect briefly (verify it's from oven-sh/bun, not malicious)
# Then run:
bash /tmp/bun-install.sh

# Verify
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
bun --version  # Should output v1.3.x or later
```

From lukemcqueen/hermes-cortex, MIT.

More from lukemcqueen/hermes-cortex