Hermes Agent Mac Setup: Install, Gateway & Migration (2026)

Hermes Agent is Nous Research's open-source, self-improving AI agent (github.com/NousResearch/hermes-agent, MIT). Unlike a single-shot chat UI, it runs a learning loop: curated memory, agent-created skills, FTS5 session search, scheduled cron jobs, and messaging gateways (Telegram, Discord, Slack, WhatsApp, Signal). This guide walks through a Mac setup—MacBook or a headless Mac mini—without assuming you rent cloud hardware.

Why run Hermes on a Mac

Hermes targets “runs anywhere,” but macOS is a practical default:

• Native installer — one-liner install.sh supports macOS (plus Linux/WSL).
• Apple Silicon — Python 3.11 via uv, Node for tooling, ffmpeg/ripgrep for media and search tools.
• Gateway process — hermes gateway stays up while you chat from Telegram; a desktop Mac that sleeps breaks that unless you move the gateway to an always-on host.
• OpenClaw path — hermes claw migrate imports memories, skills, and messaging settings from ~/.openclaw if you already run OpenClaw on Mac mini.

Compare discipline layers: Obra Superpowers adds process skills; Hermes adds runtime, tools, and channels—they stack, not compete.

Architecture on macOS

External reference: Hermes documentation and Apple Mac mini specs if you size RAM for gateway + Docker backends.

Provider flexibility: hermes model switches among Nous Portal, OpenRouter (200+ models), OpenAI, Anthropic, NVIDIA NIM, and custom endpoints—no code changes.

Eight-step Mac install runbook

1. Step 1 — Prerequisites — - macOS 13+ recommended, 16 GB RAM if you enable Docker terminal backend + gateway concurrently. - Xcode CLI tools: xcode-select --install - Homebrew optional; the installer pulls uv, Python 3.11, Node, ripgrep, ffmpeg.
2. Step 2 — Run the official installer — ```bash curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash ``` Reload shell: ```bash source ~/.zshrc # or ~/.bashrc ```
3. Step 3 — Verify CLI — ```bash hermes doctor hermes --version ``` doctor reports missing binaries, venv issues, or PATH problems.
4. Step 4 — First-time setup wizard — ```bash hermes setup ``` Interactive flow: LLM provider, API keys, default model, enabled toolsets. Shortcut for Nous bundled tools: ```bash hermes setup --portal ``` (OAuth + Tool Gateway for search, images, TTS, browser—optional.)
5. Step 5 — Pick a model and tools — ```bash hermes model hermes tools ``` Enable only what you need—each tool adds context and failure surface.
6. Step 6 — Smoke-test the TUI — ```bash hermes ``` In-session: /model, /skills, /new, /usage. Ask a small task; confirm tool calls stream in the TUI.
7. Step 7 — Optional messaging gateway — ```bash hermes gateway setup hermes gateway start ``` Pair Telegram (or other platforms) per messaging docs. Use /stop on mobile to interrupt a run. For 24/7 gateway on a Mac that must not sleep: disable sleep on a spare Mac mini, or run gateway on a remote host via SSH terminal backend (Step 8).
8. Step 8 — Migrate from OpenClaw (if applicable) — ```bash hermes claw migrate --dry-run hermes claw migrate ``` Imports SOUL.md, MEMORY.md, skills → ~/.hermes/skills/openclaw-imports/, messaging configs, and allowlisted API keys. Full option list: hermes claw migrate --help.

Terminal backends: local Mac vs SSH

Configure via hermes tools and config file—see tools documentation.

Troubleshooting

hermes: command not found

Pattern: Shell cannot find ~/.local/bin/hermes.

Fix:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc

Re-run installer if binary missing: curl -fsSL .../install.sh | bash

hermes doctor reports Python/uv errors

Pattern: Wrong Python version or broken venv.

Fix:

curl -LsSf https://astral.sh/uv/install.sh | sh hermes update hermes doctor

Contributor path (manual): clone repo, ./setup-hermes.sh per README.

Gateway connected but agent idle / no reply

Pattern: Gateway running, Telegram messages ignored.

Fix: Check hermes gateway logs, verify bot token in config, confirm your user ID is allowlisted (DM pairing). Restart:

hermes gateway stop hermes gateway start

On Apple Silicon, keep Docker Desktop updated when you enable the docker backend—stale VM images are a common source of slow first tool calls. For teams that already run scheduled jobs, wire Hermes cron to the same machine that hosts your gateway so pairing tokens and allowlists stay in one ~/.hermes/ tree.

When benchmarking providers, log token usage with /usage inside the TUI before you enable every tool category. That single habit prevents surprise bills when browser or image tools pull large contexts on every Telegram message.

If you colocate Hermes with other agents on one host, allocate at least one CPU core per active gateway worker and monitor ~/.hermes/ disk growth from FTS5 session indexes.

FAQ

Related reading

• 8B local model tuning: stop agent loops
• Hermes Trajectory Compressor: cut AI bills 10×
• Hermes Agent cron: Discord daily digest
• Hermes Agent MCP dev toolchain guide
• Obra Superpowers install guide
• OpenClaw Mac mini install guide