2026 Hermes Agent Install Guide: From One-Line curl to Telegram 7x24 Gateway on macOS, Linux, and Mac Cloud (2026)

1. Who this install guide is for

If you already read our three-layer memory article, you know why Hermes wants an always-on host. This page is the how: the exact commands from Nous Research’s Hermes Agent repo through a working Telegram bridge. You will install with the upstream script, run hermes doctor until warnings are green, complete hermes setup, pin models with hermes model, create a bot in BotFather, then run hermes gateway setup and hermes gateway install so messages flow while you sleep. The guide covers macOS (launchd), Linux VPS (systemd), and Mac cloud nodes you SSH into—without assuming you already own a Mac mini. For TCO context after install, see the Pi vs VPS vs Mac mini comparison.

2. Pain points before you run curl

1. Install succeeds, Gateway does not. Missing API keys, wrong terminal.backend, or port collisions with other agents leave Telegram silent even though hermes --version works.
2. Telegram tokens on a sleeping laptop. BotFather gives you a token in thirty seconds; keeping long-polling or webhook delivery alive needs a process that never suspends—home MacBooks and WSL2 violate that daily.
3. Linux VPS “works” but fights macOS workflows. Hermes supports seven terminal backends and 20+ channels on Linux, yet Skills that touch Xcode, Keychain, or Apple notifications still push you toward native macOS or a rented Mac node.

3. Platform comparison: MacBook vs Pi vs VPS vs Mac mini rental

Use the table to pick where you run the runbook below—not whether Hermes is worth installing. Most production Telegram bridges land on either a dedicated Linux VPS with systemd or a rented Mac mini M4 because both stay online without fighting your commute laptop.

4. Reference specs (2026)

These numbers are useful when justifying hardware to yourself or finance:

• Installer coverage: official install.sh targets macOS, Linux, and WSL2; one Gateway process can attach 20+ messaging channels per Nous documentation.
• Model surface: OpenRouter exposes 300+ models; local Ollama / LM Studio routes are supported when RAM allows—plan 16GB minimum on Apple Silicon for 8B–13B side routing plus Gateway overhead.
• Terminal backends: seven documented modes (local shell, Docker, SSH, Singularity, Modal, Daytona, Vercel Sandbox)—most Telegram-only users stay on local until they need sandboxed tools.

5. Seven-step install runbook

Step 1 — Choose host and baseline packages

On macOS, install Xcode Command Line Tools (xcode-select --install). On Ubuntu/Debian VPS, install curl, git, and build-essential. Create a dedicated Unix user hermes without production signing keys. Confirm outbound HTTPS and, for Telegram webhooks, a stable public IP or reverse tunnel plan.

Step 2 — One-line install from upstream

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

Re-open the shell so PATH updates apply. If you are on a rented Mac cloud node, run install over SSH exactly as you would locally—no separate “cloud edition.”

Step 3 — Doctor, then interactive setup

hermes doctor
hermes doctor --fix   # review diffs before accepting
hermes setup

hermes doctor catches missing Node binaries, unset API keys, and Gateway port conflicts. hermes setup walks default workspace paths under ~/.hermes. Export provider keys via environment variables when possible instead of plaintext in config files.

Step 4 — Pin models

hermes model list
hermes model set default openrouter/anthropic/claude-sonnet-4
# optional local route:
hermes config set inference.ollama.base_url http://127.0.0.1:11434

Pick one “fast/cheap” model for classification and one “hard reasoning” model for multi-step Skills. Mixed local + cloud routing keeps Telegram responsive without runaway API bills.

Step 5 — Telegram via BotFather

In Telegram, open @BotFather, run /newbot, copy the HTTP API token, and restrict allowed chats if you operate a personal agent. Store the token in your secret manager, then export it for setup:

export TELEGRAM_BOT_TOKEN="123456:ABC..."
hermes gateway setup

Follow prompts to pair the channel. For webhook mode you need HTTPS termination; long-polling is simpler on a home NAS but still requires an always-on process.

Step 6 — Install Gateway service

hermes gateway install
hermes gateway status

On macOS this typically writes a LaunchAgent; on Linux, a systemd user unit. Confirm the service name with hermes gateway status before logging out of SSH.

Step 7 — Acceptance smoke tests

hermes gateway restart
# send a Telegram message; expect a reply within one model RTT
hermes cron add "0 7 * * *" "Send heartbeat: Gateway alive"

Reboot the host once. If Telegram still answers and the cron fires, you have true 7x24 behavior. Backup ~/.hermes to encrypted storage before OS upgrades.

6. launchd vs systemd for 7x24 Gateway

macOS (launchd): prefer a LaunchAgent in ~/Library/LaunchAgents/ with KeepAlive and rotated logs under ~/Library/Logs/hermes/. After config edits:

launchctl kickstart -k gui/$(id -u)/com.nousresearch.hermes.gateway
launchctl print gui/$(id -u)/com.nousresearch.hermes.gateway | grep state

Linux (systemd): enable linger for the hermes user (loginctl enable-linger hermes), then systemctl --user enable --now hermes-gateway.service. Verify with systemctl --user status hermes-gateway. systemd is excellent on VPS; you trade away native Keychain and Apple notification integration unless you also keep a Mac node for Apple-specific Skills.

7. Error table

8. FAQ

Can I install on WSL2? Yes for experiments; Windows sleep still breaks 7x24 Telegram unless the Gateway runs elsewhere. Does reboot erase Skills? On-disk Skill documents remain; in-RAM session context clears—back up ~/.hermes before migrations. Must I use Telegram? No—hermes gateway setup also covers Slack, Discord, and other channels; Telegram is the fastest smoke test because BotFather setup takes minutes.

9. Conclusion

A MacBook gets you through Steps 1–5 in an afternoon, but lid-close sleep and home ISP drops make it a poor long-term Telegram host. Raspberry Pi kits save money yet fight RAM for local models. Five-dollar Docker VPS boxes stay online but add systemd friction and skip native macOS tooling. WSL2 on Windows inherits desktop sleep policies. Once you have run curl -fsSL …/install.sh | bash, fixed hermes doctor, and proven BotFather pairing, the durable pattern is the same: park hermes gateway install on hardware that never suspends. For most readers that means launchd on a Mac mini M4-class machine—owned or rented.

Renting a VPSMAC Apple Silicon Mac cloud host bundles predictable monthly spend, SSH access, optional Screen Sharing for debugging, and wipe-on-return when you rotate projects. You keep the same install commands as on a desk mini; you only change where the shell runs. That is the fastest path from one-line curl to a Telegram agent that is actually awake at 3 a.m.—without tying your daily laptop to Gateway uptime.