Hermes Agent is an MIT-licensed agent from Nous Research with a self-improving loop: it creates skills from experience, persists memory with periodic nudges, searches past sessions via FTS5, and models user context through Honcho. On macOS it installs as a native CLI plus optional messaging gateway—Telegram, Discord, Slack, WhatsApp, Signal, and Email—from one hermes gateway process.
This guide walks through macOS setup on Apple Silicon or Intel—install, first configuration, gateway wiring, and keeping the gateway alive with launchd. It assumes macOS 15+ on a machine you control (MacBook, Mac mini, Mac Studio, or a remote Mac you SSH into). If you already run agents in the cloud, see our separate Hermes on Mac mini M4 runbook for headless-host patterns; the commands below are identical on any Mac.
What you need before installing
| Requirement | Notes |
|---|---|
| macOS | 15+ recommended; Apple Silicon (arm64) and Intel supported per upstream install script |
| Shell | zsh (default) or bash; installer appends to ~/.zshrc or ~/.bashrc |
| Network | Outbound HTTPS for model APIs, optional Nous Portal OAuth, and messaging platform webhooks |
| Disk | Plan 2–5GB for uv, Python 3.11, Node.js, and ~/.hermes/ state; more if you store TTS assets or large skill libraries |
| RAM | 16GB comfortable for CLI + gateway + one tool-heavy turn; 24GB if you run subagents or MCP servers concurrently |
The installer pulls uv, Python 3.11, Node.js, ripgrep, and ffmpeg when missing. Verify afterward with hermes doctor.
How Hermes is laid out on macOS
After install, state lives under ~/.hermes/:
~/.hermes/
├── config.toml # providers, tools, terminal backend, gateway settings
├── skills/ # user and auto-created skills
│ └── openclaw-imports/ # after hermes claw migrate
├── memory/ # curated memory files
└── logs/ # gateway and CLI logs (paths per upstream docs)
The hermes binary symlinks to ~/.local/bin/hermes. Three surfaces matter for daily use:
- CLI (
hermes) — Interactive TUI; slash commands (/model,/skills,/compress,/new). - Gateway (
hermes gateway) — Bridges messaging platforms to the same agent loop. - Terminal backends — Where shell/file tools execute: local (default on macOS), Docker, SSH, Singularity, Modal, or Daytona.
Model routing is provider-agnostic: hermes model switches among Nous Portal, OpenRouter (200+ models), OpenAI, Anthropic, and BYO endpoints without code changes.
Step-by-step macOS setup
1. Install Hermes
Review the install script in your org before piping to shell. Upstream one-liner:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.zshrc # or: source ~/.bashrc
hermes doctor
hermes doctor should report clean checks for uv, Python 3.11, Node, ripgrep, and ffmpeg. Fix any flagged dependency and re-run.
2. Run first-time setup
Either the full wizard or Portal OAuth:
hermes setup # interactive: provider, tools, gateway hints
# OR
hermes setup --portal # Nous Portal OAuth + Tool Gateway (search, images, browser, TTS)
The wizard detects ~/.openclaw and offers migration—skip if this is a fresh install.
3. Choose model and tools
hermes model # pick provider:model (e.g. openrouter:anthropic/claude-sonnet-4)
hermes tools # enable/disable toolsets (40+ tools upstream)
hermes config set KEY VALUE # fine-grained overridesConfirm with a short CLI session:
hermes
# inside TUI: ask a question, run /usage, exit with Ctrl+D or /quit4. Migrate from OpenClaw (optional)
If you have an existing OpenClaw workspace:
hermes claw migrate --dry-run
hermes claw migrate
Imports typically include SOUL.md persona, MEMORY.md / USER.md entries, user skills, command allowlists, messaging settings, and allowlisted API keys into ~/.hermes/. See hermes claw migrate --help for presets.
5. Configure the messaging gateway
hermes gateway setup # platform tokens, DM pairing, allowed users
hermes gateway start # foreground test
Test from Telegram (or your platform): send /new, then a prompt. Use /status from the messaging side if the bot appears online but silent—often a pairing or allowlist issue (upstream Security docs).
6. Persist the gateway with launchd
Foreground hermes gateway start stops when you log out. For a Mac that stays powered on (desk Mac mini, studio machine, or remote host), create a user LaunchAgent. Example plist skeleton—adjust paths after which hermes:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>com.hermes.gateway</string>
<key>ProgramArguments</key>
<array>
<string>/Users/YOU/.local/bin/hermes</string>
<string>gateway</string>
<string>start</string>
</array>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardOutPath</key><string>/Users/YOU/.hermes/logs/gateway.stdout.log</string>
<key>StandardErrorPath</key><string>/Users/YOU/.hermes/logs/gateway.stderr.log</string>
</dict>
</plist>Load it:
mkdir -p ~/.hermes/logs
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.hermes.gateway.plist
launchctl kickstart -k gui/$(id -u)/com.hermes.gateway
Store Telegram/Discord tokens in the plist EnvironmentVariables dict or a root-owned env file referenced at boot—avoid leaving tokens only in an SSH session export.
7. Enable cron-style automations (optional)
Hermes ships a built-in cron scheduler with delivery to messaging platforms. Define jobs in natural language through the CLI or config per upstream cron docs. On macOS, cron jobs require the gateway (or CLI) process to stay running—another reason to use launchd on a non-sleeping Mac.
8. Backup ~/.hermes/
tar -czf hermes-backup-$(date +%Y%m%d).tar.gz -C ~ .hermesSkills and memory are harder to regenerate than chat logs. Snapshot before major upgrades:
hermes update
hermes doctorTroubleshooting
hermes doctor fails on Python or uv
Symptom: Doctor reports missing uv or wrong Python version.
Fix: Re-run the install script. Hermes expects Python 3.11 via uv. On macOS with Homebrew you can also brew install ripgrep ffmpeg node for ancillary tools, then hermes doctor again.
Gateway starts but bots never reply
Symptom: hermes gateway start logs "running"; DMs hang with no error in chat.
Fix: Complete DM pairing and allowlists from hermes gateway setup. Restart the gateway after changing tokens. If using launchd, confirm env vars survived the plist—launchctl print gui/$(id -u)/com.hermes.gateway shows injected environment.
CLI tools fail with permission errors
Symptom: File or shell tools error on macOS paths outside the workspace.
Fix: Review command approval settings in config (upstream Security). For full-disk paths, macOS TCC may prompt for Files/Folders access—grant on the machine where the local backend runs.
When to use an always-on Mac
A MacBook that sleeps pauses gateway delivery and cron. Teams that chat from Telegram while the agent runs elsewhere often dedicate a small always-on Mac—a desk Mac mini or a hosted macOS instance—with launchd managing hermes gateway. The setup steps in this guide do not change; only the machine's sleep policy and network reachability differ. For SSH-backend workflows (CLI on laptop, tools on remote Mac), point the terminal backend at that host in config.toml per upstream Tools documentation.
After install, run multi-agent newsletter pipelines with
Hermes subagent delegation for solopreneurs
—one boss, three parallel workers via delegate_task.
After gateway install, wire Telegram phone + Discord desktop with Hermes multi-device Gateway guide —subway handoff, /background tasks, honest session semantics.
FAQ
Does Hermes replace OpenClaw or OpenHuman?
No—different designs. Hermes emphasizes skills + memory nudges + built-in cron; OpenClaw is gateway-first automation; OpenHuman is desktop memory with OAuth auto-fetch. You can migrate OpenClaw data into Hermes with hermes claw migrate. Comparison runbooks live in our Hermes Mac mini M4 tutorial and OpenClaw install guide.
Do I need Nous Portal?
No. Portal (hermes setup --portal) bundles models and Tool Gateway under one OAuth login. You can supply OpenRouter, OpenAI, or Anthropic keys directly and enable tools à la carte.
Where is config stored on macOS?
Primary tree: ~/.hermes/ with config.toml, skills, memory, and logs. The hermes binary is at ~/.local/bin/hermes. Run hermes config subcommands rather than editing blindly—wizard values map to documented keys.
Can Hermes run on Apple Silicon Mac mini?
Yes—the install script supports macOS on Apple Silicon. Gateway + local backend run natively; no Rosetta required for the Python stack installed by uv.
How do I update Hermes?
hermes update
hermes doctorRestart launchd-managed gateway after updates: launchctl kickstart -k gui/$(id -u)/com.hermes.gateway.