curl one-liner install · hermes doctor self-check · model & Gateway · platform compare · six-step runbook
Want to run Nous Research Hermes Agent in 2026 (roughly 174k GitHub stars) but stuck on PATH, API keys, or a silent Telegram bot? This guide gives a step-by-step install path: the official curl | bash script auto-installs Python 3.11 and Node 22, hermes doctor runs twelve self-checks, hermes setup wires models and the Gateway, then you reach Telegram 24/7. You get environment requirements, a host comparison, a six-step runbook, a common-error table, and why production uptime favors Mac Mini M4 monthly rental.
Hermes Agent (Nous Research, MIT) is one of 2026's hottest open-source self-evolving AI agents on GitHub: after finishing a task class it auto-generates reusable Skills, and community reports cut tokens on similar work by roughly 38%. Through the Gateway it connects to Telegram, Discord, Slack, and 20+ platforms, with MCP and backends like Claude, OpenRouter, and Ollama. Versus OpenClaw or LangGraph, Hermes stands out on cross-session persistent memory (SESSION → MEMORY.md → USER.md) and native Skill auto-creation; the official installer runs on a $5-class VPS or a Mac—but production 24/7 and macOS browser Skills still depend on host choice.
This article skips abstract theory and fixes five install pain points: hermes: command not found, missing API keys, config drift after upgrades, silent Telegram groups, and the "installed on my laptop but it sleeps" uptime problem. If install is done and you care about memory architecture, see the companion on three-tier memory and 24/7 benchmarks.
| Requirement | Minimum | Recommended (production Gateway) |
|---|---|---|
| OS | macOS 12+ / Ubuntu 20.04+ / WSL2 | macOS 14+ (Apple Silicon) or Ubuntu 24.04 LTS |
| Python / Node | Script installs 3.11 / 22 | No manual install—trust hermes doctor |
| RAM | 4 GB (Gateway + cloud API only) | 16 GB+; local models want 32 GB UMA |
| Disk | ~1.5 GB (Skills cache included) | 20 GB SSD+ for FTS5 and log growth |
| Network | GitHub raw + LLM API reachable | Stable low latency for IM webhooks |
Assuming Python/Node first: Official install.sh uses uv for Python 3.11, Node 22, ripgrep, and ffmpeg—no sudo.
Skipping shell reload: PATH stays stale and you get command not found; run source ~/.zshrc or open a new terminal.
Skipping hermes doctor: Twelve checks catch API keys, ffmpeg, and PATH issues before you waste an hour blind-running hermes.
Browser deps on headless servers: Add --skip-browser on VPS to avoid Camoufox-style deps breaking install.
POC laptop as production: Closing a MacBook drops the Gateway and Skill compounding; 24/7 needs a dedicated host.
The same curl | bash line behaves differently by host—uptime, IO, and the macOS-native path matter. Passing the install tutorial does not mean the box suits Gateway and Skill compounding 24/7. The table below summarizes post-install production feel from community and datacenter runs.
| Platform | 24/7 availability | Skill compounding | Monthly cost feel | Best for |
|---|---|---|---|---|
| Personal MacBook | ≈ 60% (lid closed = offline) | Frequent gaps | $0 hardware + high anxiety | POC / local CLI only |
| Raspberry Pi 4B 8GB | ≈ 88% | IO bottleneck; long jobs timeout | One-time hardware | Tinkering—not production Gateway |
| x86 VPS 4GB | ≈ 99.5% | Stable; no macOS Skills | Pay-as-you-go | API + Telegram; skip browser automation |
| Mac Mini M4 rental | Datacenter SLA, ~100% over 30 days | UMA + launchd daemon; Skills keep stacking | Fixed monthly fee | Telegram 24/7 + Camoufox / local Ollama |
Install takes ten minutes; picking the right 24/7 host decides whether Skills compound or reset every week.
M4 unified memory lets Gateway (community reports ~4.2 GB resident), browser automation, and SQLite WAL share one address space; launchd on macOS aligns with the official test path better than Linux systemd. Rent one month to prove Telegram and the Skill curve before buying—see 30 days firsthand.
Steps work on macOS / Linux / WSL2; add --skip-browser on step 1 for headless VPS. Data and config default to ~/.hermes/—back up before upgrades.
One-line install: Run the official script, wait for Hermes Agent installed at ~/.hermes, then source ~/.zshrc (Linux: ~/.bashrc).
Health check: hermes doctor passes Python, Node, ripgrep, ffmpeg, PATH; hermes --version confirms v0.14+.
Configure model: hermes setup or hermes model; OpenRouter / Anthropic / Nous Portal keys land in ~/.hermes/.env.
CLI smoke test: Run hermes, dispatch a tool-calling task (e.g. count files in cwd) and confirm API flow.
Telegram: Create bot via BotFather → hermes gateway setup, pick Telegram, set token and TELEGRAM_ALLOWED_USERS; for groups, disable privacy mode and re-invite the bot.
24/7 daemon: hermes gateway install && hermes gateway start; Linux can use sudo hermes gateway install --system, macOS uses launchd user service.
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash source ~/.zshrc hermes doctor hermes setup hermes gateway setup hermes gateway install hermes gateway start hermes gateway status
Set API keys manually too: hermes config set OPENROUTER_API_KEY sk-or-xxxx or append to ~/.hermes/.env. After upgrades, if config is missing, run hermes config check && hermes config migrate.
These symptoms usually appear after the script succeeds but the service is unusable—work through the table one row at a time instead of changing model, data dir, and Gateway at once.
| Error / symptom | Likely cause | Fix |
|---|---|---|
| hermes: command not found | PATH not refreshed | source ~/.zshrc or new terminal |
| API key not set | No LLM configured | hermes model or write ~/.hermes/.env |
| Missing config after update | Version upgrade drift | hermes config check && hermes config migrate |
| ModuleNotFoundError: dotenv | Wrong system Python | Use ~/.hermes/hermes-agent/venv/bin/hermes |
| Telegram group silent | Bot privacy mode | BotFather: turn off Group Privacy; remove and re-add bot |
Hermes supports any MCP Server (GitHub, databases, browser, etc.) via mcp_servers in ~/.hermes/config.yaml; headless OAuth can use hermes mcp login plus an SSH tunnel. In production, prove one channel before stacking MCP so logs stay bisectable.
Tip: Windows has a PowerShell installer, but Dashboard /chat terminal panels need WSL2; use WSL2 + the Linux runbook here for parity with this guide.
~/.hermes/hermes-agent/, global command on PATH via script.hermes doctor covers ~12 items (Python 3.11, Node 22, ripgrep, ffmpeg, API key, etc.).Laptops and home NAS boxes pass install acceptance yet weaken Telegram 24/7 through sleep, cross-region VPS IO, or missing macOS browser Skills; Pi struggles with local 8B and long jobs. Teams treating Hermes as an always-on colleague get Mac Mini M4 rental bundling uptime, UMA, and launchd into predictable OpEx—less time reinstalling than chasing uptime on the wrong host.
If this runbook is done and you need a production 24/7 node, VpsMesh offers Mac Mini M4 cloud rental: SSH delivery, resource panel, and full ~/.hermes/ backup before off-board. See Mac Mini M4 rental pricing, deployment help at the help center, and order at the order page.
Warning: Do not change host, upgrade Hermes major version, and rewrite Telegram allowlists the same weekend—three parallel moves cannot be bisected. Stabilize hermes gateway status for 24h before touching models or MCP.
No. Official install.sh uses uv to install Python 3.11, Node.js 22, ripgrep, and ffmpeg; the repo lives at ~/.hermes/hermes-agent/. After install run source ~/.zshrc and hermes doctor for all twelve checks.
Default privacy mode makes groups respond only to / commands. In BotFather → Bot Settings → Group Privacy choose Turn off, then remove and re-invite the bot. Confirm TELEGRAM_ALLOWED_USERS includes your numeric ID and hermes gateway status shows running.
Cloud API plus single-channel Telegram: x86 VPS is enough. For macOS browser-automation Skills, local Ollama, or launchd daemons, Mac Mini M4 rental gives steadier uptime and UMA. Unsure? Rent one month to validate the Skill curve—plans on the pricing page, order at the order page.