Run Hermes Agent with a Local LLM
30 MIN
Chat from the terminal against local vLLM with the self-improving Nous Research agent (Telegram optional)
Common issues
| Symptom | Cause | Fix |
|---|---|---|
hermes: command not found after install | Shell profile not reloaded in the current session | Run source ~/.bashrc (or source ~/.zshrc) and retry. Open a new terminal if the issue persists. |
source ~/.bashrc works in an interactive terminal, but hermes is still missing from a scripted SSH command | Many Ubuntu .bashrc files return early for non-interactive shells before the installer-added PATH lines run | In automation, run export PATH="$HOME/.local/bin:$PATH" before hermes, or call ~/.local/bin/hermes directly. |
sudo: hermes: command not found during gateway install, uninstall, or printed sudo hermes … steps | sudo resets PATH and does not see the user-level hermes shim | Run which hermes as your normal user, then invoke that path with sudo, e.g. sudo "$(which hermes)" uninstall or sudo /full/path/from/which/hermes gateway …. |
| Installer prints "Setup wizard skipped (no terminal available)" | The installer was launched from a non-interactive shell, CI job, or SSH command without a usable TTY | Either re-run hermes setup in an interactive terminal, or configure the endpoint directly: hermes config set model.provider custom, hermes config set model.base_url http://localhost:8000/v1, and hermes config set model.default nvidia/Qwen3.6-35B-A3B-NVFP4. |
Installer cannot install ripgrep / ffmpeg, or prints Non-interactive mode and no terminal available | Optional helper install needs sudo, but the current shell cannot prompt for a password | Install manually in an interactive terminal with sudo apt install -y ripgrep ffmpeg. Hermes still runs without them, but file search is slower and TTS voice-message support is limited. |
Browser tools show system dependency not met, or Playwright Chromium install fails | Playwright needs Linux shared libraries installed through sudo, and the installer could not obtain sudo access | Core chat still works. To enable browser tools, run cd ~/.hermes/hermes-agent && npx playwright install --with-deps chromium in an interactive terminal and enter your sudo password. |
You want the gateway to start at boot, but hermes gateway install creates a user service | Current Hermes installs a user service by default unless --system is supplied | Use sudo "$(which hermes)" gateway install --system --run-as-user "$USER" (or replace $(which hermes) with ~/.local/bin/hermes if needed). |
hermes uninstall --yes says it requires an interactive terminal, or still prompts for uninstall options | The uninstaller protects data deletion and expects a real TTY for confirmation | Run it directly in your terminal, or allocate a TTY over SSH (ssh -t <host> 'hermes uninstall'). For a full wipe, select Full uninstall and type yes when prompted. |
| Installer asks about OpenClaw import / migration | Another agent framework was previously installed | For this playbook, answer n. OpenClaw migration is out of scope here and can leave gateway or messaging state confusing. If you already migrated by mistake, use Start over from scratch below. |
~/.hermes still exists after uninstall | Uninstaller preserves data unless you explicitly remove it | This is expected in some flows. Remove manually only if you want a full wipe: rm -rf ~/.hermes (see Start over from scratch). |
| Hermes installer can't list any models at the model-selection prompt | vLLM is not running yet or is still loading the checkpoint | Sanity-check the endpoint in another terminal: curl http://localhost:8000/v1/models should return a "data" array containing your served model handle (for example nvidia/Qwen3.6-35B-A3B-NVFP4). If it is empty or unreachable, confirm the vLLM container is up and has finished loading (watch its terminal for Application startup complete), then re-run the Hermes installer. |
Connection refused to http://localhost:8000/v1 from Hermes | vLLM server not running, still loading, or wrong port | Confirm the vLLM container is up and listening on 8000 (docker ps, then curl http://localhost:8000/v1/models). If it exited, relaunch it (see Instructions — Step 2). |
| Out-of-memory or very slow inference | Served model is too large for available GPU memory, or other GPU workloads are competing | Check usage with nvidia-smi, free GPU memory by closing other workloads, or relaunch vLLM with a lower --gpu-memory-utilization / --max-model-len (or a smaller model handle) and re-point Hermes via hermes model. |
hermes update fails or the gateway does not restart | Gateway service still bound to the previous version, or insufficient permissions on a system-service install | Re-run sudo "$(which hermes)" update if the gateway was installed as a System service and plain hermes update cannot restart it. If the service is stuck, restart it manually: sudo systemctl restart <hermes-gateway-unit>. |
| Cannot resume a previous session | The <sessionId> value is missing or wrong | Use hermes --resume <sessionId> with the exact ID Hermes printed when you /exit that chat. If the ID is lost, start a new session with hermes (omit --resume). |
Start over from scratch
If gateway or messaging state is inconsistent (for example after an accidental OpenClaw migration), uninstall Hermes, remove leftover data, then re-run Instructions from Step 3:
export PATH="$HOME/.local/bin:$PATH"
HERMES_BIN="$(command -v hermes || printf '%s\n' "$HOME/.local/bin/hermes")"
sudo "$HERMES_BIN" uninstall
rm -rf ~/.hermes
Then reinstall with the installer command in Instructions — Step 3.
NOTE
sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'
Optional — Telegram messaging issues
Only relevant if you followed the optional Telegram section at the bottom of Instructions.
| Symptom | Cause | Fix |
|---|---|---|
Telegram bot never answers; gateway logs show timeouts or TLS errors to api.telegram.org | Outbound HTTPS to Telegram is blocked on the current network (common on locked-down corporate LANs) | From the hardware platform, run the HTTPS check in Instructions — Optional — Set up Telegram messaging. If it hangs or fails, move to a network that allows Telegram or ask IT to allow HTTPS to api.telegram.org. Terminal Hermes can still work without Telegram. |
| Choosing Telegram during gateway setup immediately shows “setup complete” without token / user ID prompts | Stale or partial Hermes gateway config; installer short-circuit | After source ~/.bashrc, run hermes gateway setup, select Telegram, and complete token and allowed-user steps. Install or restart the systemd service using the printed commands (with sudo "$(which hermes)" if needed). |
/start shows “Unknown command” (or similar) in Telegram | Bot does not define a custom /start handler | Send a normal text message such as hello after /start. Hermes responds to conversational text, not necessarily slash commands. |
| Pasting the Telegram bot token shows nothing on the screen | Expected — the installer hides token characters as a security measure | Paste the token, then press Enter. The installer should respond with Telegram token saved. |
Telegram bot does not reply when you send hello | Gateway service not running, your account is not in the allowed user IDs list, or outbound HTTPS to Telegram is blocked | (1) Confirm Telegram HTTPS from the hardware (Instructions — optional Telegram section). (2) List Hermes units with systemctl list-units --type=service --all, locate the gateway unit by name, then sudo systemctl status <hermes-gateway-unit> and sudo journalctl -u <hermes-gateway-unit> -e --no-pager -n 80. (3) If logs show reachability to Telegram but messages are ignored, verify your numeric user ID is in the allowed list via hermes gateway setup or the Hermes messaging gateway docs. |