2026 Hermes Agent Install Guide: macOS / Linux / WSL2 One-Line Setup, Telegram Gateway & 7×24 Troubleshooting

Six install pitfalls: why README-only often fails

By late May 2026, Nous Research shipped Hermes v0.15.2 with both pip install hermes-agent and the classic curl | bash installer. Stars and release notes move fast; forum posts often skip the friction that shows up in the first hour on a real machine. Treat the list below as a pre-flight checklist before you blame the project or reinstall from scratch.

1. PATH not refreshed: the script appends hermes to ~/.zshrc or ~/.bashrc. Without source or a new terminal window, you get hermes: command not found even though install succeeded—the most common false negative.
2. System Python vs venv: running python3 -m hermes outside the project venv can miss dependencies such as dotenv. The supported entry point is ~/.hermes/hermes-agent/venv/bin/hermes.
3. CLI only, no model brain: the interactive shell opens, then immediately errors with API key not set because hermes setup or hermes model was skipped.
4. Gateway confused with CLI: Telegram needs a long-running hermes gateway process. A one-off hermes chat session never bridges messages to your phone.
5. Telegram group privacy mode: new bots default to slash-command-only behavior in groups. Without disabling Group Privacy in BotFather, operators assume the bot is broken.
6. Half-finished upgrades: jumping from v0.14 to v0.15 can shift config fields. Run hermes config check && hermes config migrate before debugging mysterious Missing config after update errors.

One-line contrast with OpenClaw: OpenClaw excels at multi-channel Gateway operations and npm or Docker Compose deployment patterns familiar to Node shops. Hermes optimizes for cross-session MEMORY.md and USER.md, post-task Skill capture, and MCP tooling. You can run both on one Mac, but this article stays in the install lane—concept and hardware trade-offs live in the memory architecture post; week-by-week Skill growth is in the 30-day experience post.

If you are evaluating agents for a team, separate three questions early: Can we install it on our OS baseline? Can we attach a model provider our security team approves? Can we keep a Gateway process alive through nights and weekends? This runbook answers the first two in one sitting; the third is why MACCOME publishes hosting comparisons alongside install guides.

Security reviewers often ask whether Hermes phones home beyond your chosen LLM. In practice, outbound traffic is dominated by the model API, Telegram long-polling or webhook endpoints, optional MCP servers you configure, and GitHub when Skills update. Document those endpoints in your change ticket the same way you would for any self-hosted agent framework. Nothing in the default install replaces your need for secret storage discipline: treat ~/.hermes/.env like production credentials, restrict SSH keys on shared hosts, and rotate Telegram tokens if a laptop with a dev copy was ever lost.

Environment requirements: what you actually need on disk

The official installer bundles Python 3.11 (via uv), Node.js 22, ripgrep, and ffmpeg when you use the full script path. Your responsibilities are narrower: working git, outbound HTTPS to GitHub raw and your LLM vendor, and enough disk for Skills plus session SQLite. Headless Linux servers that never touch browser automation should pass --skip-browser to avoid Camoufox weight.

Remote Mac nodes behave like local shells: SSH in, paste the same commands, and run Gateway under launchd or systemd once validated. Latency to your API region matters more than CPU brand for cloud-routed models; unified memory helps when browser Skills and multiple Gateways share one box.

WSL2 deserves an explicit note because Windows is the fastest-growing install surface in issue trackers. Keep the Hermes tree on the Linux ext4 filesystem inside WSL, not on /mnt/c, or file watchers and SQLite WAL behavior become flaky under DrvFS. Disable Windows sleep while you validate Gateway overnight; many “Linux Gateway bug” reports trace back to the host PC suspending WSL. When you outgrow that constraint, migrate the same ~/.hermes tarball to a native Linux VPS or a rented Mac—no reinstall required if permissions are preserved.

Corporate proxies sometimes block raw GitHub fetches. If curl | bash fails mid-stream, mirror the install script internally or clone the repository and run the script from a checkout on allowed storage. The pip path (pip install hermes-agent) is an acceptable air-gapped-friendly alternative when your artifact registry mirrors PyPI. Either way, run hermes doctor before declaring victory; it catches half-configured Node or Python stacks that manual copies often miss.

Eight-step runbook: from one command to Telegram online

These steps are identical on macOS, Linux, and WSL2. Validate each gate before moving on—skipping hermes doctor usually costs more time than running it.

1. One-line install: run the official script (see bash block below). Success prints Hermes Agent installed at ~/.hermes or equivalent in recent builds.
2. Reload shell: source ~/.zshrc or source ~/.bashrc, or open a fresh terminal tab.
3. Health check: hermes doctor exercises roughly a dozen checks (Python, Node, PATH, API keys). hermes --version should report v0.15.x on current stable.
4. Configure models: first-time users run hermes setup; existing keys can use hermes model or hermes config set OPENROUTER_API_KEY sk-or-xxxx into ~/.hermes/.env.
5. Smoke test: launch hermes and ask for a lightweight task such as listing the current directory to confirm tool invocation works end to end.
6. Create Telegram bot: message @BotFather, run /newbot, store the token securely; use @userinfobot for your numeric user ID.
7. Configure Gateway: hermes gateway setup and choose Telegram, or set TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS manually in env.
8. Daemonize: interactive testing with hermes gateway; production with hermes gateway install && hermes gateway start (launchd on macOS, systemd on Linux).

Step eight is where “installed” becomes “production.” A foreground Gateway dies when SSH drops unless you use tmux; user-level services survive logout on macOS when installed correctly, and --system installs suit Linux servers you control with sudo. After start, send a direct message to the bot before testing groups—DM path validates token and allow-list without group privacy noise.

Choosing an LLM provider in 2026

For daily tool use with cloud routing, OpenRouter remains the fastest multi-model experiments path. Enterprise teams standardized on Claude should wire Anthropic API or OAuth in hermes model. Zero-config trials can use Nous Portal via hermes setup --portal. Privacy-sensitive workflows point Ollama base URLs through the same wizard. v0.15 adds Grok as a provider and x_search tooling—enable only what your task needs inside hermes tools to keep context lean.

Document which provider each environment uses: staging might run cheap models while production uses Sonnet-class APIs. Hermes stores keys under ~/.hermes/.env; rotate them there, not in shell exports alone, so Gateway and CLI share one source of truth.

Telegram-specific pitfalls beyond privacy mode: never commit bot tokens to git; regenerate in BotFather if leaked. Use numeric user IDs in TELEGRAM_ALLOWED_USERS, not @handles. For teams, list every operator who may DM the bot, or you will debug “works for me, not for colleague” allow-list gaps. Group testing should wait until DM works—otherwise you chase two variables at once. If you need multiple environments (dev/stage/prod), run separate bots and tokens so staging prompts never hit production memory files.

After Gateway starts, verify with hermes gateway status and send a message that exercises a tool (for example, “what is my hostname?”). Tool success proves the agent loop is wired; a plain echo only proves Telegram connectivity. Schedule a calendar reminder to upgrade within a week of upstream tags—v0.15.x still moves quickly, and hermes config migrate is cheaper than rebuilding ~/.hermes from scratch after a breaking release note.

Hard metrics you can quote: version, stars, and Skill compounding

• GitHub stars (June 2026 snapshot): about 174,720, MIT license, frequently trending—confirm the current tag on Releases before pinning docs (stable line v0.15.2 / 2026.5.29.2).
• Install footprint: roughly 1.5 GB with default Skills registry; Gateway resident set often near 4.2 GB when browser automation is enabled—smoother on Apple Silicon unified memory.
• Skill compounding (field report, linked 30-day post): Skills grew 3 to 19 in thirty days with about 38% lower tokens on repeat task classes—only if the host stays online 24/7; sleep or reboot breaks the closed loop.

Stars measure attention, not your personal readiness. The numbers that matter operationally are install size on your disk quota, Gateway RSS under your RAM plan, and whether sessions and Skill files accumulate while you are offline. If Gateway uptime is under 90% in month one, treat Skill savings as hypothetical until uptime improves.

When briefing management, pair the 38% repeat-task token figure with uptime percentage and median Telegram response time—not stars. Executives approve rental spend when you show compounding requires infrastructure, not when you show another trending repo. Link internally to the 30-day report for narrative proof and to the architecture article for why MEMORY.md and SQLite both matter once Gateway stays up.

Twelve common errors and fixes

Use this table during first-week support. When a row does not match, capture hermes doctor output and Gateway logs before opening a GitHub issue—upstream moves quickly on v0.15.x.

Platform comparison: laptop, VPS, and rented Mac Mini M4

Passing install proves the binary runs. Telegram production and Skill compounding prove the host stays available. The matrix below is the same framing we use when customers ask whether a personal MacBook is “good enough” for Hermes—usually for a afternoon POC, rarely for a month of Gateway traffic.

A MacBook on your desk is excellent for steps one through five in this guide. It becomes a poor fit when step eight must survive travel, sleep, and OS updates without someone remembering to reopen a terminal. VPS boxes solve uptime but may lack the macOS-native installer ergonomics and Camoufox browser Skill path teams already validated on Apple Silicon. Raspberry Pi class hardware can boot Gateway, yet I/O and thermal limits show up on long agent tasks. Dedicated Mac Mini M4 rental—what MACCOME operates—targets the intersection: real macOS, datacenter power, and launchd patterns that match this article verbatim.

FinOps teams sometimes compare rental to a one-time Mac Mini purchase. Include electricity, cooling, static IP or DDNS, physical theft risk, and the hour cost of babysitting OS updates in that spreadsheet—not just hardware MSRP. Rental converts capex into an opex line that scales down when the experiment ends, which matters when you are proving Hermes to a skeptical stakeholder. If the pilot succeeds, you can still buy metal later; many teams keep rental for production Gateway and use laptops only as SSH clients.

Closing: install is step one; uptime decides whether the agent gets cheaper

Following the eight steps above, most readers can reach a first successful Hermes CLI session and Telegram Gateway reply within 30 to 60 minutes, assuming API keys are already approved by their org. The failure modes after that are rarely “install broken again”—they are operational: laptop sleep, token rotation without Gateway restart, or under-provisioned RAM when browser Skills load.

Three alternatives each have a clear weakness. (a) A laptop cannot reliably stay online 24/7, so Gateway connections and Skill writes stall whenever the machine sleeps. (b) A small x86 VPS lacks the macOS-native curl | bash path and Camoufox browser Skill workflow many Hermes tutorials assume. (c) Buying your own Mac Mini shifts capex, home broadband, noise, and physical security onto you instead of a monthly operations line item.

If Hermes already saves you repetitive work and you want predictable monthly cost, SSH handoff in minutes, and the option to tarball ~/.hermes/ before moving hosts, a MACCOME dedicated Mac Mini M4 cloud node is usually the better production shape: real Apple Silicon, native launchd for Gateway, and the same commands in this guide without rewriting paths. Read the architecture decision article for MEMORY.md and SessionDB depth, the 30-day field report for Skill curves, then pick a region on the Mac Mini rental rates page when you are ready to commit uptime to the agent instead of your travel schedule.