2026 Hermes Agent Install and Deploy Guide
macOS, Linux VPS, Telegram Gateway, and 7×24 Production Checklist

Hermes Agent (Nous Research, MIT) installs with a single pipeline: curl -fsSL https://get.hermes-agent.org | bash. Everything the agent learns lands under ~/.hermes/ on the machine you choose. That sounds simple until you need Telegram to answer at 2 a.m. while your MacBook is asleep, or until a VPS reboot leaves the gateway down. This article is the operational counterpart to our 24/7 host and memory architecture guide and the thirty-day Skill-doc review: same agent, different lens. Here you get host prerequisites, platform differences between macOS and Linux, the setup wizard, doctor checks, gateway autostart, and a six-step runbook you can paste into a runbook doc.

01. Prerequisites: host matrix, network, and what you need before curl

Hermes is not a hosted SaaS. You supply the CPU, disk, outbound network, and LLM credentials. Before touching the installer, decide which machine will stay online when you are not at the keyboard.

Account and secret checklist:

• LLM provider key — OpenAI, Anthropic, OpenRouter, or a self-hosted endpoint Hermes supports. You will enter these during hermes setup or via environment variables documented in the upstream README.
• Telegram Bot Token — create via @BotFather; you need HTTPS egress from the host to api.telegram.org for long-polling or webhook modes.
• SSH access — for VPS or MacDate day-rental nodes, confirm your key loads and sudo is unnecessary (Hermes installs in user space under the admin account).
• Disk — allocate at least 10 GB free; state.db, skills, and optional embedding caches grow slowly but monotonically.

Network rules that block installs in the wild: corporate proxies that MITM get.hermes-agent.org, outbound firewall rules on port 443, and VPS images without curl or a current CA bundle. From the host, a quick preflight is curl -fsSLI https://get.hermes-agent.org and curl -fsSLI https://api.telegram.org — both should return HTTP headers without certificate errors.

02. Install: curl pipeline on macOS and Linux VPS

The supported entry point is the official installer served from get.hermes-agent.org. It detects macOS versus Linux, places the hermes CLI on your PATH, and scaffolds ~/.hermes/ with default config stubs. You do not need Docker for a standard CLI + gateway deployment, which is why many builders prefer a bare Mac mini or a MacDate rental over container-only VPS templates.

macOS (native, including Mac mini M4)

SSH or sit at the machine as the user who will own the agent. macOS 14+ or macOS 26 on Apple Silicon is the happy path Nous tests most often. Run:

The script may prompt for passwordless prerequisites (Xcode CLI tools are not required for the minimal path, but having them helps if you later compile optional plugins). After install, list the tree: ls -la ~/.hermes/ should show config.json, empty or seed memories/, and a fresh state.db once the first session runs.

Linux VPS (Ubuntu 22.04 / Debian 12 typical)

Same curl pipe, often executed as a dedicated Unix user hermes if you segregate daemons. Install curl, ca-certificates, and git if your image is minimal. Systemd integration for the gateway comes in module 06; the installer itself only needs an interactive shell.

WSL2 on Windows follows the Linux path; treat it like a VPS for gateway uptime — sleep the laptop and the agent stops. If you are evaluating hardware spend, compare rental days on the Mac mini M4 pricing guide against months of VPS fees before you commit to either.

Security hygiene: run the installer only from the official domain. Pipe-to-bash is convenient; if your org forbids it, download the script, inspect it, then execute locally. Hermes stores secrets in ~/.hermes/ with user-only permissions — keep that directory out of world-readable backups and public dotfile repos.

03. Configure LLM: hermes setup, API keys, and model defaults

Install places binaries; hermes setup is the interactive wizard that wires your default model provider, stores API keys in the Hermes config layer, and sets sane defaults for tool use and memory plugins. Run it immediately after curl on a fresh host — skipping setup and hand-editing JSON works for power users but costs time when doctor later reports missing provider blocks.

Expect prompts roughly along these lines (exact labels follow upstream releases):

• Primary LLM provider — pick OpenAI-compatible, Anthropic, or a custom base URL for local gateways.
• API key entry — pasted once, written to the secure config store under ~/.hermes/, not echoed to shell history if you use the wizard.
• Default model ID — choose a model that supports tool calling; Hermes relies on tools for memory, skills, shell, and channel replies.
• Optional fallbacks — some configs allow a cheaper model for summarization; accept defaults on first pass.

Environment-variable overrides remain valid for CI and Terraform-managed VPS images. Pattern: export OPENAI_API_KEY or ANTHROPIC_API_KEY in the systemd unit or LaunchAgent plist, then run setup once non-interactively if your version supports flag-based config. For MacDate rentals, set keys during the first SSH session and avoid leaving them in shell profiles on shared jump boxes — use the wizard or a root-owned env file readable only by the admin user.

Smoke-test inference before Telegram:

A one-line reply confirms keys, model ID, and outbound HTTPS to the provider. If you see rate-limit or 401 errors, fix setup before gateway work — otherwise Telegram users get silent failures that look like bot bugs.

Optional: local Ollama on Mac mini M4

Hermes is model-agnostic. Cloud APIs are the fastest path to production; Ollama on a 16–24 GB UMA Mac mini is optional for privacy experiments. Point setup at your Ollama OpenAI-compatible URL, keep cloud fallback for tool-heavy tasks if local models struggle. This is independent of gateway install — same hermes setup, different base URL.

04. Validate: hermes doctor, memory status, and common failures

hermes doctor is your post-install and post-migration health check. Run it after setup, after restoring a tar backup of ~/.hermes/, and after every OS update that might relocate Python or Node dependencies the installer bundled.

Doctor typically verifies: CLI on PATH, config parseable, provider credentials present, gateway binary dependencies, SQLite state.db integrity, and channel subsystem readiness. hermes memory status reports MEMORY.md / USER.md footprint, session index health, and whether optional plugins (Hindsight, Mem0, etc.) are enabled — useful when you migrate from a VPS experiment described in the thirty-day review.

Failure catalog from production installs:

• Provider auth failed — re-run hermes setup or rotate the API key; doctor surfaces 401/403 from the upstream API.
• Permission denied on ~/.hermes/ — you copied a backup as root; chown -R admin:staff ~/.hermes on macOS or the equivalent on Linux.
• Corrupt state.db — restore yesterday's tarball; do not delete skills manually unless you intend to lose procedural memory.
• Gateway port in use — stale process after crash; hermes gateway stop then start clean.
• Hindsight hang on Apple Silicon — if you enabled local embeddings, see issue #7135 and force CPU embeddings before calling doctor again.

Treat doctor as a gate: green output before you expose Telegram to teammates. The memory architecture post goes deep on caps (2,200 / 1,375 characters for MEMORY.md / USER.md); doctor reminds you when files approach limits so new facts actually appear in the next session snapshot.

05. Telegram gateway: channels, hermes gateway, and reachability

Telegram is the most common production channel for solo builders: BotFather token, allowlist your user ID, start the gateway daemon. Discord follows a parallel hermes channels add discord path; this section focuses on Telegram because mobile reach is the usual 7×24 acceptance test.

Create the bot and allowlist yourself

1. Message @BotFather, /newbot, copy the token.
2. Export TELEGRAM_BOT_TOKEN in the shell or store via setup-adjacent channel config per current docs.
3. Add your numeric user ID to the allowlist / dmPolicy block in Hermes config so random users cannot drive your agent.

Send a test message from your phone. Latency under a few seconds on a MacDate APAC node is typical; home uplink or oversubscribed VPS tiers show up as multi-minute delays that users blame on the model. hermes gateway status should report running; if it exits, check doctor and systemd/launchd logs.

Hermes does not require exposing a public inbound port on 3978 the way some OpenClaw Gateway tutorials do — Telegram long-polling initiates outbound connections from your host. Still, lock admin SSH behind Tailscale or key-only auth; the bot token is a secret comparable to an API key.

Keep the gateway alive 7×24

Starting the gateway in an SSH session is fine for hour-one testing. Production means autostart:

• macOS — register a LaunchAgent that runs hermes gateway start at login and after reboot; verify with sudo launchctl list | grep -i hermes or the plist label your installer documents.
• Linux — enable the systemd user or system unit shipped or documented alongside the install; systemctl --user enable hermes-gateway pattern after first manual start succeeds.

Reboot test: restart the VPS or Mac mini, wait three minutes, message the bot. If silence, the gateway did not autostart — fix before trusting Cron or natural-language schedules. The 24/7 host guide explains why missed overnight windows hurt skill compounding; here the fix is operational: autostart plus monitoring.

06. Six-step 7×24 runbook: rent or SSH, install, setup, doctor, gateway, backup

Consolidated runbook for MacDate renters and self-hosters. Budget 75–90 minutes including Telegram pairing and one reboot test.

1. Provision the host. Rent Mac mini M4 on MacDate or SSH into your VPS. First-time renters: day-rental FAQ. Confirm HTTPS egress and >10 GB disk.
2. curl install. curl -fsSL https://get.hermes-agent.org | bash, then hermes --version.
3. hermes setup. Walk the wizard, set provider and model, run hermes chat smoke test.
4. hermes doctor. Fix every red line; run hermes memory status on migrated backups.
5. Telegram + gateway. BotFather token, hermes channels add telegram, hermes gateway start, mobile ping, enable autostart, reboot test.
6. Backup and ops rhythm. Nightly tar czf hermes-backup-$(date +%F).tar.gz ~/.hermes/, scp to laptop or object storage; before MacDate release, download the archive — wipe destroys the agent brain.

When to read the sibling posts: use the memory guide for Pi vs VPS vs Mac mini TCO and three-layer memory theory; use the thirty-day review for Skill-document compounding and VPS migration war stories. This install guide gets you live; those articles help you decide whether to keep the host twelve months.

MacDate conversion path

If you are not ready to buy a desk Mac mini, MacDate bare-metal rental gives you native macOS curl install, datacenter bandwidth for Telegram, and isolated ~/.hermes/ without contaminating your laptop. Pay daily or weekly while you run the six steps above, prove gateway uptime for two weeks, then compare buy versus extend using the pricing guide and bare-metal rates. MacDate is an Apple hardware rental platform, not affiliated with Nous Research branding.

Three install datapoints worth pinning in your notes:

• Installer URL is canonical — get.hermes-agent.org tracks releases; bookmark the GitHub repo for issue search, not for day-one install.
• Setup before gateway — ordering reduces Telegram-side "bot online but model errors" support burden.
• Doctor after every restore — migrating from VPS without doctor caught half our team's broken state.db permissions in the field review.