2026 Hermes Agent Install Guide: macOS, Linux, VPS One-Click Deploy + Telegram 24/7 Gateway

Hermes Agent from Nous Research is an MIT-licensed agent platform that sits between a terminal UI and a multi-channel gateway. One core process can serve Telegram, Discord, Slack, WhatsApp, Signal, and CLI sessions while sharing the same memory stack: ephemeral session context, durable skill documents distilled after hard tasks, and persistent user-model markdown plus SQLite FTS5 episodic search. Tool calling, subagents, cron-style scheduling, and optional MCP servers extend the runtime without forking the memory store.

Install success is only the first gate. Users message your bot from mobile; they expect answers that reference prior decisions, not a cold start every morning. That requires a host where state.db, skill folders, and gateway webhooks survive reboots and OS updates. A developer MacBook is fine for the steps below; moving Telegram production traffic to a sleeping laptop is not. Teams that outgrow hobby hosting typically migrate the same config tarball to a dedicated cloud Mac or always-on VPS once the learning loop proves value.

This article assumes you have shell access, outbound HTTPS, and permission to store API keys on disk. Hermes supports 200+ models through OpenRouter, Nous Portal, OpenAI-compatible endpoints, and other providers documented upstream. Pick one provider before install so you can validate the full path in a single session.

Most install tickets are not broken curl pipes. They are mismatched hosts, missing dependencies, or keys stored in the wrong place. The table maps platform expectations against what Hermes actually needs for a Telegram gateway that stays up.

• Python and Node adjacency: The official installer pulls runtime dependencies. On minimal VPS images, install build essentials and ensure curl, git, and a working python3 exist before you pipe the script.
• Dedicated Unix user: Run Hermes under a non-root account with a fixed home directory. Mixing gateway state with root or shared login users complicates token permissions and backup.
• Disk layout: Plan separate space for state.db, skill trees, and logs. A 20GB root volume fills quickly once episodic search and skill distillation run for weeks.
• Network: Telegram requires stable outbound HTTPS and, for webhook mode, a reachable HTTPS endpoint or long-polling fallback documented in gateway config. Home NAT and carrier-grade NAT on cheap VPS pools cause the classic works-on-my-Mac, dead-on-VPS pattern.
• Secrets hygiene: Never commit BotFather tokens or LLM keys. Store them in mode-600 files outside git and reference paths from gateway config only.

Run hermes doctor after install to surface missing dependencies before you blame Telegram. Fixing environment drift upfront saves hours of gateway log archaeology.

The upstream installer is the same on macOS and Linux. VPS provisioning differs only in how you SSH in and which user owns the home directory. Follow these six steps in order; they mirror what I use on fresh NUKCLOUD instances and clean Ubuntu images.

1. 01
   Prepare the host: On macOS, confirm Xcode Command Line Tools or accept the installer prompt. On Ubuntu or Debian VPS, run sudo apt update && sudo apt install -y curl git python3 python3-venv build-essential. Create a dedicated user such as hermes with a home directory on persistent disk, not a tmpfs mount.
2. 02
   Run the official installer: As that user, execute the one-line install script from Nous Research. Wait for completion; the script places the CLI on your PATH and initializes default config directories. Pin the release you tested rather than tracking main on a production gateway.
3. 03
   Verify binary and version: Run hermes --version and confirm the CLI responds. If the shell cannot find the binary, log out and back in so profile PATH updates apply, or source the profile snippet the installer prints.
4. 04
   Run health diagnostics: Execute hermes doctor and resolve every reported warning before configuring models. Doctor checks Python packages, disk permissions, and gateway prerequisites. Skipping this step is the fastest route to a Telegram bot that installs but never stays online.
5. 05
   Launch the TUI once interactively: Start hermes tui over SSH with a pseudo-TTY. Confirm the terminal UI loads, accepts keyboard input, and can reach your network. This proves the core runtime before you detach into a daemon.
6. 06
   Snapshot baseline: Record macOS minor version or /etc/os-release, timezone, install path, and directory listing for config and memory folders. Tarball this tree before Telegram traffic arrives so you can restore if a bad upgrade corrupts FTS5 indexes.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes --version
hermes doctor
hermes tui

On a fresh VPS, provision through your provider panel first, attach SSH keys, harden sshd, and only then run the installer. If you are sizing a production SKU, use the order page to pick disk and RAM before install so SQLite and skills never share a cramped root volume with OS snapshots.

Hermes without a model endpoint is an empty gateway. Configuration lives in YAML and environment files under the Hermes home directory; exact filenames evolve with releases, so treat upstream docs as authoritative and keep your pinned version bookmarked.

Provider setup: Export your API key in a restricted file, for example ~/.hermes/secrets/openrouter.env with mode 600, then reference it from the provider block. OpenRouter is the common default for multi-model access; Nous Portal and OpenAI-compatible base URLs work for teams with existing contracts. Set a default model slug that matches your budget and latency target. Avoid switching providers on a live gateway without backing up state.db and skill directories first.

Memory paths: Confirm MEMORY.md, USER.md, and skill folders sit on persistent volumes. On Docker or ephemeral VPS images, bind-mount these paths explicitly or you will lose compounding memory on container recreate.

CLI validation: From the TUI or one-shot CLI mode, send a prompt that requires tool use or memory write, then ask a follow-up in a new session that should recall the fact. If recall fails after a controlled reboot, fix disk persistence before opening Telegram to humans.

export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxx"
export HERMES_DEFAULT_MODEL="anthropic/claude-sonnet-4"

Re-run hermes doctor after editing provider config. Doctor output is the fastest signal that your key is visible to the same user context that will run the gateway daemon.

Telegram is the most requested first gateway because BotFather setup is quick and mobile clients are everywhere. Treat token handling as production security work, not a demo shortcut.

BotFather flow: In Telegram, open @BotFather, run /newbot, choose a display name and username ending in bot, and copy the HTTP API token. Store the token in a mode-600 file such as ~/.hermes/secrets/telegram.token. Reference that path from the Hermes gateway configuration block for Telegram; do not paste tokens into shell history or commit them to dotfiles tracked in git.

Gateway start: Use the documented Hermes gateway subcommand for Telegram, typically started after provider env is loaded. Test with a direct message to your bot before adding it to group chats. Group mode may require privacy settings adjusted via BotFather depending on whether the bot must read all messages.

macOS persistence with launchd: Create a LaunchAgent plist that loads your secrets env file, sets WorkingDirectory to the Hermes home, and runs the gateway binary with KeepAlive true. Load with launchctl bootstrap under the dedicated user. Verify with launchctl print after reboot.

Linux VPS persistence with systemd: Create a user systemd unit with EnvironmentFile pointing at your secrets, Restart=on-failure, and WantedBy=multi-user.target or user lingering enabled. Enable lingering for the Hermes user so the gateway survives SSH logout: loginctl enable-linger hermes.

[Unit]
Description=Hermes Telegram Gateway
After=network-online.target

[Service]
EnvironmentFile=%h/.hermes/secrets/openrouter.env
EnvironmentFile=%h/.hermes/secrets/telegram.env
ExecStart=%h/.local/bin/hermes gateway telegram
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target

Admin access: Reach the TUI over SSH with port forwarding; never expose management ports on the public internet. Monitor log growth, gateway restart counts, and Telegram webhook or long-poll errors daily for the first week. After seven days of stable uptime, schedule weekly tarball backups of state.db and skill trees.

Command cheat sheet for day-two ops: hermes --version for drift checks, hermes doctor after upgrades, hermes tui for interactive debug, gateway logs via journalctl --user -u hermes-telegram.service on Linux or log show --predicate filters on macOS. Pin these in your runbook next to on-call contacts.

The installer is deliberately cross-platform; hosting choice determines whether Telegram users notice gaps. Shared VPS pools tempt with five-dollar stickers, but bandwidth jitter, oversubscribed CPUs, and broken long-polling sessions show up exactly when your user model starts to feel intelligent. Home Mac minis work when you control power and ISP; enterprise teams usually prefer a cloud Mac or hardened VPS with documented tenant boundaries.

For teams that need compounding Hermes memory without buying hardware before validation, metered cloud Mac on NUKCLOUD preserves cash flow while you measure recall quality and support load. Generic minute-based macOS VPS offerings often oversell CPU and drop gateways during summarization jobs. When Telegram is production-facing, stable disk, predictable outbound networking, and a host that survives reboots matter more than saving ten dollars a month on an oversubscribed pool.