2026 Hermes Agent Step-by-Step Install Guide: From Zero to Telegram 7×24 Gateway

Nous Research’s Hermes Agent crossed roughly 174,000 GitHub stars by June 2026, yet most production incidents still trace to skipped install validation—not model quality. Unlike our earlier guides on persistent memory architecture or the Pi vs VPS vs M4 hardware test, this runbook stays on the operational path: one-command install, hermes doctor, model configuration, hermes gateway setup for Telegram, supervision, and a troubleshooting ladder you can hand to on-call without rereading README fragments.

1. Three install pain points that look like model failures

Hermes support threads in May and June 2026 repeat the same three infrastructure mistakes. Number them before you rotate API keys or blame Telegram.

1. Running install.sh on the wrong UNIX user. The installer writes state under ~/.hermes/ for whoever executes the pipe. Teams that curl-as-root then sudo-down to a service account discover empty gateways, permission errors on skills/, and Telegram tokens bound to a home directory nobody supervises. Always create a dedicated user first—hermes on Linux, an isolated macOS account on Apple Silicon—and run the script as that identity.
2. Skipping hermes doctor after partial upgrades. Release v2026.5.29.2 tightened gateway module checks. Operators who git-pulled without rerunning hermes doctor saw green CLI version strings while the long-lived gateway process still loaded stale channel drivers. Treat doctor output as a gate: zero errors before hermes setup or hermes gateway setup.
3. Telegram configured on a sleeping host. BotFather tokens are easy; keeping long-polling or webhook callbacks alive on a MacBook that closes every evening is not. Users report “bot worked yesterday, silent today” when the host slept, DHCP changed, or systemd/launchd never registered the gateway. Pair Telegram setup with explicit process supervision on hardware that stays online.

These pain points mirror OpenClaw gateway incidents documented in our macOS launchd troubleshooting guide. Hermes is a separate MIT stack, but the host discipline is identical: one canonical user, one supervised daemon, one place for credentials.

2. Hermes Agent v2026.5.29.2: what you are installing

Hermes Agent is Nous Research’s open-source personal AI agent framework, licensed under MIT, with a curl-to-bash installer that lands binaries and configuration scaffolding in ~/.hermes/. The project’s GitHub visibility—on the order of 174k stars in mid-2026—reflects demand for agents that compound skills across sessions rather than resetting every chat. This guide does not re-derive the three-layer memory model; read the persistent memory decision guide when you need MEMORY.md semantics. Here we focus on the install surface: CLI entrypoints, gateway channels, and the minimum viable Telegram deployment.

After install you interact with four commands repeatedly. hermes doctor validates dependencies, versions, and filesystem layout. hermes setup walks provider keys, default models, and workspace paths. hermes gateway setup registers outbound channels—Telegram, and others depending on your build—writing tokens into the gateway config tree. Day-two operations add skill editing under skills/, where Nous documents skill self-evolution: the agent refines its own playbooks after successful runs, which is why repeat workflows report roughly 38% lower token usage once Skill Documents stabilize.

3. Host matrix: MacBook vs VPS vs Mac mini M4 vs remote Mac

Install.sh runs on macOS and Linux, but “runs” is not the same as “belongs in production.” Use the matrix when stakeholders ask why you rejected a $6 VPS or your daily-driver laptop for a Telegram gateway that must answer at 3 a.m.

The hardware test article quantified twelve-week uptime across Pi, VPS, and owned M4. For install day, the decision rule is simpler: if Telegram must respond while you sleep, do not finish gateway setup on hardware that also rides in your backpack.

4. Prerequisites before curl install.sh

Gather these before you pipe bash. Missing any item adds thirty minutes of forum archaeology.

• Operating system: macOS 14 or newer on Apple Silicon, or Ubuntu 22.04/24.04 LTS on x86_64/ARM64 VPS. Windows is out of scope—use WSL only for experiments, not Telegram production.
• Node.js: Node 20 LTS or Node 22 current; hermes doctor prints the exact minimum for v2026.5.29.2.
• LLM provider credentials: At least one API key—OpenRouter, Anthropic, OpenAI, or a local endpoint if you colocate inference. Have billing limits set; first-run setup probes models and can burn tokens.
• Telegram BotFather token: Message @BotFather, create a bot, copy the HTTP API token, disable privacy mode if the bot must read group messages.
• Network: Outbound HTTPS to Telegram API endpoints and your LLM provider; inbound webhook only if you choose webhook mode over long-polling.
• Dedicated UNIX user: Non-root, login shell, home directory on fast SSD—this user owns ~/.hermes/ forever.

5. Eight-step install and Telegram gateway runbook

The sequence below assumes macOS on Apple Silicon; Linux steps differ only in supervision (systemd vs launchd). Execute as the dedicated service user throughout.

1. Create the service user and log in. On macOS, System Settings → Users → Add Account. On Linux, sudo adduser hermes. SSH or screen-share as that user; confirm echo $HOME points where you expect state to live.
2. Run the official installer. Paste the Nous Research one-liner exactly:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The script installs CLI binaries, creates ~/.hermes/, and adds PATH hooks to your shell profile. Open a new shell or source ~/.zshrc before continuing.

3. Validate with hermes doctor. Run hermes doctor and fix every red line—missing Node modules, outdated CLI, unwritable skills/. Doctor is idempotent; rerun after each fix until clean.
4. Complete hermes setup. Interactive hermes setup binds default model, provider API keys, timezone, and operator name into USER.md seeds. Choose a model with enough context for your longest Skill Document; many teams start with a mid-tier frontier model via OpenRouter for cost control.
5. Seed the skills directory. Confirm ~/.hermes/skills/ exists. Add one markdown Skill Document—on-call ack, deploy checklist, or Telegram greeting flow. Snapshot before enabling self-evolution jobs so you can roll back a bad rewrite.
6. Configure Telegram via hermes gateway setup. Run hermes gateway setup, select Telegram, paste the BotFather token when prompted, and choose long-polling (simplest behind NAT) or webhook (requires public HTTPS URL). The wizard writes channel config under the gateway tree; note the path doctor prints for audits.
7. Register process supervision. On macOS, create a LaunchAgent plist that runs hermes gateway start or the documented daemon subcommand at login and keep-alive. On Linux, install a systemd unit with Restart=always. Without supervision, Telegram stops the moment your SSH session ends.
8. Acceptance smoke tests. DM the bot with a unique string, mention it in a test group if group mode is enabled, and verify replies within 60 seconds. Send three varied prompts on separate days; confirm USER.md and skill files update. Only then call the gateway production.

6. Model configuration and 38% token economics

Install success is not the same as affordable operation. Hermes defaults are conservative, but Telegram groups can spike token usage when history grows unbounded.

During hermes setup, set a primary model and at least one fallback provider. Nous documents multi-provider routing in v2026.5.x; mirror the pattern you already use for OpenClaw if both stacks share a host. Cap max tokens per reply in gateway settings when available, and trim group history to the last N messages for noisy channels.

Skill self-evolution is the long-term cost lever. After roughly two weeks of repeat workflows—daily standup summaries, incident acks, deploy notifications—Skill Documents converge and Hermes reports about 38% fewer tokens on identical tasks because the agent stops re-deriving steps from scratch. That number comes from Nous Research’s public benchmarks on recurring ops playbooks; your mileage depends on skill quality and how often you invalidate skills with manual edits.

For local inference on Apple Silicon, pair Hermes with Ollama only after you validate memory headroom on M4. Our rented Mac mini M4 local agent guide covers sizing; Hermes can consume the same unified memory pool if you colocate services under separate users.

7. Troubleshooting ladder after gateway setup

When Telegram goes quiet, walk this ladder top to bottom—do not randomize BotFather tokens on step one.

1. Process alive? launchctl list | grep hermes on macOS or systemctl status hermes-gateway on Linux. Restart the supervised unit if the PID is missing.
2. Doctor clean? Rerun hermes doctor after any manual edit to config files. YAML typos often pass human review but fail gateway load.
3. Telegram token valid? Curl the Telegram getMe endpoint with your token in a throwaway shell. Revoked tokens fail silently until the gateway logs are inspected.
4. LLM provider healthy? Provider 401/429 errors mimic dead bots. Check gateway logs for HTTP status codes before blaming Telegram.
5. Group privacy settings? If the bot only answers DMs, disable BotFather privacy mode or mention the bot explicitly per Telegram rules.
6. Host network? Sleeping laptop, CGNAT, or firewall egress blocks cause intermittent long-poll timeouts. Move to always-on hardware if outages correlate with local time evening hours.

8. Quotable numbers for architecture reviews

Paste these into slide decks when finance asks why Hermes deserves dedicated hardware.

• ~174,000 GitHub stars on Nous Research Hermes Agent as of June 2026—social proof, not a SLA.
• MIT license—no vendor lock-in on the agent core; you own ~/.hermes/ on disk.
• v2026.5.29.2—pin this semver in runbooks; verify post-install with hermes doctor.
• 38% token reduction on repeat tasks after Skill Documents mature—measure monthly spend before and after skill stabilization.
• 16 vs 32 GB UMA on Mac mini M4—16 GB for single-operator Telegram + API tools; 32 GB when colocating browser automation or local vectors.
• 60-second reply SLA—reasonable acceptance target for Telegram smoke tests on a warm gateway with frontier API latency under 3 seconds.
• $72–$240/year indicative VPS range versus CapEx on owned M4—see the hardware test article for twelve-week TCO detail.

9. From working Telegram bot to 7×24 production host

If you followed the eight steps on a MacBook or home mini, you now have proof: Hermes installs cleanly, doctor passes, Telegram replies, and skills begin compounding. That is a valid milestone for personal automation and internal demos. It is not yet a production posture for a bot your team relies on when pagers fire at night.

Laptops introduce sleep, travel, and accidental logout. Home Mac minis introduce ISP DHCP churn, residential power blips, and single-custodian risk when the one engineer who knows the LaunchAgent plist is on vacation. Linux VPS hosts solve uptime but break macOS-native skills, Keychain-adjacent browser profiles, and the unified memory story that makes M4 attractive when you add local tools later.

SFTPMAC remote Mac mini M4 rental targets the gap: Apple Silicon with launchd supervision, isolated tenant users for Hermes state, SFTP-friendly sync for skills/ from CI, and backbone connectivity that keeps Telegram long-polling alive through long tool runs. Provision Node 22, run the same curl install.sh as this guide, pair BotFather once from a managed phone, and wire team access without exposing your personal laptop. When incidents strike, you restart a supervised gateway on hardware that already passes doctor—not a machine in someone’s backpack.

For memory architecture depth, read the M4 persistent memory guide. For hardware receipts, read the three-way hardware test. This install guide gets you to Telegram; renting a Mac from SFTPMAC keeps Hermes there 7×24.

10. FAQ

What is the official Hermes Agent install command? curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash as the dedicated service user.

Where does Hermes store state? Under ~/.hermes/ including skills/, USER.md, and gateway configuration—backup this tree before upgrades.

How do I connect Telegram? Create a BotFather bot, run hermes gateway setup, select Telegram, paste the token, restart the supervised gateway process.

Must I run hermes doctor after every update? Yes. v2026.5.x gateway modules fail silently if doctor warnings are ignored.

Can I install on Linux VPS only? Yes for API-centric bots; production teams colocating macOS skills or OpenClaw gateways should prefer Mac mini M4 or SFTPMAC rental.

What about the 38% token claim? It reflects skill self-evolution on repeat workflows in Nous benchmarks; measure your own spend after two weeks of stable Skill Documents.