macOS / Linux one-line deploy · hermes doctor · LLM setup · Gateway 7×24 · remote Mac acceptance
Who is this for? You starred Nous Research’s Hermes Agent (roughly 170k GitHub stars by June 2026) and want a working CLI, a configured LLM, and Telegram access from your phone—but you are stuck on PATH, API keys, or a Gateway that looks online yet never replies in groups. Bottom line: run the official curl | bash installer, pass hermes doctor, wire LLM keys in ~/.hermes/.env, then install the Gateway as a launchd or systemd service for true 7×24 uptime. For production, pair this walkthrough with why Hermes needs a Mac that never sleeps and consider renting a Mac Mini M4 instead of a lid-closed laptop. In this article: requirements → install → doctor + LLM → Telegram → Skills → error table → platform matrix → FAQ.
Hermes Agent is Nous Research’s MIT-licensed “self-evolving” agent: after it completes a task, it can distill the successful trajectory into a reusable Skill under ~/.hermes/skills/. Community benchmarks in early 2026 report token use dropping roughly 38% on repeat workflows once Skill libraries grow (for example, from 3 to 19 Skills over 30 days of daily use). A Gateway process connects Telegram, Discord, Slack, WhatsApp, and twenty-plus other channels; MCP servers extend tools without forking the core repo.
Compared with OpenClaw (stronger IM playbooks on this site) or CrewAI / LangGraph (orchestration frameworks you assemble yourself), Hermes ships as an installable product: CLI, doctor checks, channel adapters, and opinionated memory files (SESSION → MEMORY.md → USER.md). If you already read our three-layer memory and Mac Mini rental piece, treat this article as the hands-on complement: how to install, verify, and keep the daemon alive.
As of June 2026, support tickets cluster on three topics: whether the installer really bundles Python and Node, whether Gateway can survive reboots via launchd/systemd, and whether Telegram group privacy mode is why the bot ignores normal messages. We follow real ticket order below—not a README paste. Official docs: hermes-agent.nousresearch.com/docs/getting-started/installation; source of truth for versions: github.com/NousResearch/hermes-agent.
Underestimated prerequisites: operators assume they must hand-install Python 3.11, Node 22, ripgrep, and ffmpeg. The script already does.
No model brain: CLI launches but inference fails because hermes setup or ~/.hermes/.env was skipped.
Gateway only in foreground: closing SSH kills Telegram; hermes gateway install was never run.
Group privacy: the bot answers / commands in groups but ignores plain text until BotFather privacy is disabled and the bot is re-invited.
The installer probes your OS and pulls dependencies. Use the table to decide if the machine is viable and whether you should stay on cloud APIs or plan for local models.
| Item | Minimum | Recommended |
|---|---|---|
| OS | macOS 12+, Ubuntu 20.04+, WSL2 | macOS 14+ (Apple Silicon) / Ubuntu 24.04 LTS |
| Python / Node | Installer provides 3.11 / Node 18+ | Installer defaults to Node 22; no sudo required |
| RAM | 4 GB (Gateway + cloud APIs only) | 16 GB (Ollama or browser automation) |
| Disk | ~1.5 GB including Skill cache | 20 GB+ SSD if storing local model weights |
| Network | GitHub raw + LLM API reachability | Stable low-latency egress for Telegram long polling |
Quotable facts: (1) You do not need to manually install Python, Node, ripgrep, or ffmpeg for a standard install. (2) On headless Linux VPS hosts, append --skip-browser to skip browser automation payloads. (3) Native Windows remains beta-grade; WSL2 + Linux installer is the supported path for most Windows developers.
In Terminal, run the official script from the main branch (re-check the URL in Nous docs before you paste in production):
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
The script typically: installs uv → Python 3.11 → Node.js 22 → ripgrep and ffmpeg → clones into ~/.hermes/hermes-agent/ → exposes a global hermes command → seeds default Skill registries. Success looks like ✅ Hermes Agent installed at ~/.hermes in the installer output.
Run source ~/.zshrc (macOS) or source ~/.bashrc (Linux) so PATH picks up the shim.
On servers without a GUI: curl -fsSL .../install.sh | bash -s -- --skip-browser.
Run hermes doctor and confirm the health checklist passes (see Section 04).
Run hermes setup to bind your LLM provider (Section 04 table).
On a rented remote Mac, complete the first install over VNC if macOS prompts for Screen Recording or Accessibility—pure SSH cannot click TCC dialogs.
Windows: iex (irm .../install.ps1) with files under %LOCALAPPDATA%\hermes\; use WSL2 for dashboard terminal features when docs call for a Unix shell. Termux on Android can run the same curl | bash flow with environment detection in the script.
VNC login → open Terminal → run the installer → screenshot hermes doctor for your runbook → hermes setup for API keys → switch to SSH for day-two ops. The ~/.hermes/ tree holds Skills, SQLite session storage, and .env. Before you return hardware, archive with tar czf hermes-backup.tgz ~/.hermes and restore on the next node.
hermes doctor hermes --version hermes setup # full wizard; best for first run # or: hermes model
hermes doctor is your acceptance gate: it checks the virtualenv, CLI shim, config files, optional browser stack, and channel prerequisites. Treat a green doctor run like a CI pipeline you would not skip before pointing Telegram traffic at the box.
| Provider | Strength | How to configure |
|---|---|---|
| Nous Portal | Subscription route; 300+ models | hermes setup --portal (OAuth) |
| OpenRouter | Multi-model experiments | API key in ~/.hermes/.env |
| Anthropic / OpenAI | Claude / GPT families | API key or OAuth per wizard |
| Ollama / vLLM | Local inference | Base URL + key; plan for 16 GB+ RAM |
Set keys explicitly when you prefer files over wizards: hermes config set OPENROUTER_API_KEY sk-or-xxxx or append to ~/.hermes/.env. Smoke-test with hermes in interactive mode—for example, ask it to summarize today’s AI headlines and confirm tool calls return without 401 errors.
Second quotable pack: doctor should pass before Gateway install; version string helps support threads; local Ollama on 8 GB hosts often swaps under concurrent Skill retrieval—match RAM to the memory article’s 16 GB floor / 24 GB comfort guidance.
In Telegram, open @BotFather, run /newbot, and store the bot token securely.
Message @userinfobot (or equivalent) to read your numeric user ID.
Run hermes gateway setup, choose Telegram, and paste token + ID—or set TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS in .env.
Test with hermes gateway in the foreground; DM the bot from your phone.
Production: hermes gateway install && hermes gateway start. macOS uses launchd; Linux may use sudo hermes gateway install --system for systemd.
Group chats: default bots run in privacy mode and only see slash commands. In BotFather, disable Group Privacy, remove the bot from the group, and invite it again—otherwise you will debug the wrong layer.
15-minute acceptance checklist: (1) DM reply works. (2) hermes gateway status shows running. (3) Reboot the host and confirm the service auto-starts. (4) Logs show no repeating 401 (bad key) or 429 (quota). On Linux, tail with journalctl -u hermes-gateway -f; on a rented Mac, filter Console.app for hermes during VNC sessions.
| Command | Purpose |
|---|---|
| hermes | Interactive chat CLI |
| hermes tools | Enable or disable tool surfaces |
| hermes gateway status | Daemon health |
| hermes update | Pull latest release |
| hermes config check | Validate config after upgrades |
Skill evolution only compounds when the host stays online: successful runs become Markdown procedures under ~/.hermes/skills/ for cheaper repeat work. Sleep your MacBook every night and you pause that flywheel even though files remain on disk.
Declare MCP servers in ~/.hermes/config.yaml under mcp_servers (for example GitHub). Use least-privilege tokens. Browser-oriented MCP stacks are most complete on macOS; headless Linux may miss dependencies—another reason teams migrate Gateway to a Mac Mini after the POC phase.
| Symptom | Likely cause | Fix |
|---|---|---|
| hermes: command not found | PATH not refreshed | source ~/.zshrc or new terminal |
| API key not set | LLM not configured | hermes model or edit .env |
| Missing config after update | Schema drift on upgrade | hermes config migrate |
| ModuleNotFoundError: dotenv | Wrong Python binary | Use ~/.hermes/.../venv/bin/hermes |
| Telegram group silence | Privacy mode | BotFather off + re-invite bot |
| Platform | 7×24 availability | Skill compounding | Best for |
|---|---|---|---|
| Personal MacBook | ~60% (sleep breaks Gateway) | Interrupted | Weekend POC only |
| x86 VPS (4 GB) | ~99.5% uptime | Stable but no macOS-only tools | Linux-only operators |
| Mac Mini M4 rental | Datacenter SLA | launchd + unified memory | Telegram production users |
A new Mac Mini M4 16 GB runs roughly $599–$699 in U.S. retail (June 2026 bands—confirm before you budget). Amortized over 24 months that is about $25–$30 per month plus power, cooling, and outage risk you own. VNCMac monthly rent near $195.9 converts CapEx into OpEx while you prove whether Hermes saves you two hours a day. Unified memory keeps Gateway (~4.2 GB in typical traces), browser CDP, and SQLite WAL on one pool—4 GB x86 VPS hosts often swap during Skill FTS maintenance.
Third stat line for internal decks: ~170k GitHub stars (June 2026), ~38% repeat-task token reduction cited in community Skill benchmarks, 12+ doctor checks before you declare production, 15-minute Telegram acceptance window.
No. Official install.sh uses uv to install Python 3.11, Node 22, ripgrep, and ffmpeg, then registers the hermes CLI.
Most install and Gateway steps work over SSH. First-time macOS privacy prompts and some OAuth browser callbacks need VNC—same pattern as our OpenClaw remote Mac guides.
Entry point remains the official install script. Upgrade with hermes update; if configs drift, run hermes config check && hermes config migrate.
The memory article explains why 7×24 disk matters for SOUL, Skills, and SQLite. This guide covers install and channel wiring. Install first, then choose your host tier.
Yes on separate directories and ports. Budget RAM accordingly—see our multi-agent on one rented Mini article for isolation patterns.
Installing Hermes is intentionally boring: one official script, one hermes doctor, one .env, one Gateway service. The gap between a demo and production is uptime—Skills compound, Telegram stays reachable, and memory files keep writing only while the machine and daemon stay up.
A sleeping laptop, flaky home Wi-Fi, or a $5 VPS throttled at peak hours turns “gets smarter over time” into “new hire every Monday.” Buying a Mac Mini M4 makes sense once you have measured year-round load. While you are still proving value, rent a physical M4 node, install Hermes over SSH, accept permissions over VNC, and tarball ~/.hermes/ before lease end.
Getting Hermes installed is step one; keeping it running is the product. Open Mac Mini M4 monthly plans when you are ready to give Gateway and Skills a host that does not clock out at 6 p.m.