2026 Hermes Agent Install Guide:
macOS / Linux + Telegram 24/7 Gateway

If you are evaluating Nous Research open-source Hermes Agent in 2026, the blocker is rarely prompt craft. It is the engineering chain: install script, Python and Node dependencies, LLM API keys, Telegram Bot tokens, and a Gateway background service. This guide targets developers and small teams who want Hermes from "runs in a terminal" to "reachable from your phone with the machine online 24/7" on macOS, Linux, or WSL2.

We start with six common install misjudgments, then an environment table and host platform matrix, followed by copy-paste curl | bash, hermes doctor, hermes setup, and Telegram Gateway steps (eight or more). For memory architecture see our three-tier memory article; for buy-vs-rent economics see the 24-month TCO piece. Rental rates on the NOVAKVM pricing page, orders on the order page. Commands below follow official documentation; reopen links after each upstream release.

[ SECTION_01 ] // PAIN_MAP Six misconceptions when installing Hermes Agent (2026)

• "I must install Python 3.11 and Node 22 myself first." The official installer pulls runtimes through uv. You only need working Git. Mixing system Python often triggers ModuleNotFoundError.
• "Install finished, so Telegram works." CLI chat and Gateway are separate paths. Channels require hermes gateway setup and a daemon process.
• "hermes: command not found means the install failed." Usually PATH was not refreshed. Open a new terminal or run source ~/.zshrc; no full reinstall needed.
• "Any Linux VPS equals a Mac." Docs are most complete on macOS. Some browser automation and macOS-only Skills behave differently on pure Linux. Verify platform notes before production.
• "I @-mentioned the Bot in a group and got silence." Telegram privacy mode limits group replies to / commands. Disable Group Privacy in BotFather and remove then re-add the Bot to the group.
• "My laptop lid closed is fine for production Gateway." Sleep pauses processes. Skill compounding and channel webhooks need a supervised always-on host, not the same bar as "install succeeded."

Official Hermes entry points below. Reopen after each release to confirm installer URL and flags.

Hermes Agent official installation docs (Nous Research)

NousResearch/hermes-agent (GitHub repository)

[ SECTION_02 ] // ENV_MATRIX Hermes Agent environment requirements and where to deploy

The table summarizes pragmatic floors for local install. Gateway with cloud APIs only uses less RAM than co-located local models. Pricing and inventory are not listed here; check the pricing page.

Validating install only? A laptop is enough. For Telegram plus Skill compounding over weeks, put Gateway on a production Mac that does not sleep.

[ SECTION_03 ] // INSTALL Hermes Agent one-line install: curl script, PATH, and hermes doctor

On macOS, Linux, WSL2, or Termux, the official one-liner clones the repo to ~/.hermes/hermes-agent/ and registers a global hermes command:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.zshrc
hermes doctor
hermes --version

Headless servers that skip browser automation can pass the flag documented upstream:

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

hermes doctor checks Python, Node, ripgrep, ffmpeg, PATH, and API keys. Fix every reported failure before moving on. Native Windows PowerShell installer is still early beta; production teams usually choose WSL2 plus the Linux commands above (see official Installation chapter).

After the CLI works, you can attach optional MCP servers in ~/.hermes/config.yaml and authenticate with hermes mcp login. Headless hosts often tunnel OAuth callbacks over SSH. Provider choice (OpenRouter for experiments, Anthropic or OpenAI for production, Ollama for on-box inference) does not change the install path; only hermes setup or hermes model needs updating.

[ SECTION_04 ] // RUNBOOK Eight steps from model config to Telegram Gateway daemon

1. Finish install and refresh PATH: Confirm ~/.hermes exists, run hermes doctor, clear blockers.
2. Configure LLM: New users run hermes setup. Existing keys can use hermes model or ~/.hermes/.env (OpenRouter, Anthropic, OpenAI, Ollama base URL, etc.).
3. CLI smoke test: Run hermes with a real task (for example, summarize file types in the current directory) and confirm tools and API billing.
4. Create Telegram Bot: Message @BotFather, run /newbot, save the token. Use @userinfobot for your numeric user ID.
5. Write Gateway config: Prefer hermes gateway setup and choose Telegram; or set TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS manually.
6. Foreground Gateway test: Run hermes gateway, DM the Bot from your phone, confirm replies before backgrounding.
7. Install daemon: On macOS use hermes gateway install plus hermes gateway start (launchd). On Linux try sudo hermes gateway install --system and tail with journalctl -u hermes-gateway -f.
8. Backup discipline: Archive ~/.hermes/ on a schedule. Machine swap or lease end needs directory-level restore, not binary-only reinstall, or the agent "forgets."

hermes gateway setup
hermes gateway install
hermes gateway start
hermes gateway status

For group chats read official Messaging docs on privacy mode. After disabling Group Privacy, remove the Bot from the group and invite it again.

Hermes Agent Telegram integration docs (GitHub)

[ SECTION_05 ] // TROUBLESHOOT Common Hermes install and Gateway errors

Running these steps on a remote Mac? Session and access baselines live in the help center. When you need dedicated Apple Silicon and predictable lease teardown, evaluate monthly bare-metal rental instead of keeping a personal laptop awake indefinitely.

[ SECTION_06 ] // HARD_FACTS Citable technical facts and NOVAKVM close

• Installer behavior: Official script uses uv for Python 3.11, Node 22, ripgrep, ffmpeg, and places the repo at ~/.hermes/hermes-agent/. (Source: Installation docs; re-verify after release.)
• Config root: Environment variables and Gateway tokens default to ~/.hermes/.env; cross-session memory and Skills persist under the same tree. (Source: official Memory / Setup docs.)
• Model-agnostic: Hermes connects to Anthropic, OpenAI, OpenRouter, GitHub Copilot, Ollama, and others. Model IDs and billing follow each provider.
• MCP extension: Declare mcp_servers in ~/.hermes/config.yaml; complete OAuth with hermes mcp login (headless setups often use SSH tunnels).
• Version check: Trust hermes --version and GitHub Releases; do not copy star counts or uncited benchmark rankings from secondary posts.

Treat "install works" as the starting line. A personal laptop suits weekend POC, but sleep, OS updates, and mixed personal data interrupt Gateway and Skill compounding. Pure Linux VPS runs the API path yet may lose macOS browser automation and tooling fidelity. If CLI trials prove Hermes worth keeping, a practical production path is rent a dedicated Mac Mini M4 for two to four weeks, watch Gateway logs, then decide on hardware purchase.

Pick concurrency and disk tier on the NOVAKVM pricing page, provision from the order page, and follow the eight steps here for install plus Telegram always-on. For teams that need the documented macOS install path, 24/7 launchd supervision, and predictable lease wipe, NOVAKVM Mac Mini bare-metal cloud rental usually beats leaving a primary laptop powered on around the clock.