2026 Hermes Agent Mac Setup Checklist:
What to Prepare Before Your Weekend Install

For a quick trial, follow the official Quickstart. If you want Hermes to stay useful on your Mac, work through the checklist below before you run the installer.

1Before you install: hardware, system, and backup

2Prepare dependencies: Git is the only prerequisite

Per the Installation guide, the one-line installer automatically provisions uv, Python 3.11, Node.js v22, ripgrep, and ffmpeg—you do not need Homebrew Python or Node first. Confirm Git is ready:

• →Git: git --version should print a version; install Xcode CLT before you start, not mid-install.
• →Shell: default zsh; after install run source ~/.zshrc to refresh PATH.
• →Optional Nix: Nix users follow the Nix setup guide instead of the curl installer—pick one path.

3Prepare accounts and secrets

The installer will configure an LLM provider; having keys ready avoids half-finished runs:

• →At least one API key from OpenRouter, Anthropic, OpenAI, or another supported provider.
• →Store secrets in ~/.hermes/.env and run chmod 600 ~/.hermes/.env.
• →Never commit keys to project Git; use TELEGRAM_ALLOWED_USERS and similar allowlists—avoid GATEWAY_ALLOW_ALL_USERS=true.

4Create a safe workspace

Official per-user layout: code at ~/.hermes/hermes-agent/, data under ~/.hermes/ (config, logs, pairing, sandboxes).

• →Use a dedicated subdirectory as the agent workspace—do not grant the entire home folder.
• →Logs: ~/.hermes/logs/ (Gateway writes gateway.log).
• →Custom install path: set HERMES_INSTALL_DIR=... before running the installer (see official docs).

5Install & first run

Install (minimum viable):

Then source ~/.zshrc → hermes or hermes setup → hermes model.

First-run verification:

• ✓which hermes → ~/.local/bin/hermes
• ✓hermes doctor shows no blockers (missing API key will suggest hermes model)
• ✓Send a real prompt and confirm model replies and tool calls
• ✓If you enable file or terminal tools, grant Full Disk Access and related permissions in System Settings as needed

6Keep it running: launchd persistence

Running hermes in a Terminal window only lasts for that session; the messaging gateway needs a daemon:

• 1After CLI is stable: hermes gateway setup (configure Telegram, Discord, Slack, etc. per the current support list)
• 2hermes gateway install → plist at ~/Library/LaunchAgents/ai.hermes.gateway.plist
• 3hermes gateway start → hermes gateway status
• 4Logs: tail -f ~/.hermes/logs/gateway.log
• 5After installing new Homebrew or nvm tools, rerun hermes gateway install to refresh PATH in the plist

7Recovery: what to check when install fails

824-hour watch list

• ①Reboot the Mac → hermes gateway status still shows running
• ②Drop network for 5 minutes, restore, and see whether the gateway recovers or needs a manual start
• ③Spot-check ~/.hermes/logs/ for error stacks
• ④Review LLM billing so tool loops do not spike cost
• ⑤Trigger one risky command on purpose and confirm approval still works

9Mac mini is a better fit for 24/7 agents

Hermes gateways, BlueBubbles bridges, and local toolchains all assume a stable macOS host. Mac mini M4 pairs Apple Silicon unified memory with roughly 4 W idle draw—ideal as a quiet home or small-team agent node: native Unix, Homebrew, Docker, and launchd without WSL; Gatekeeper and FileVault shrink long-term exposure; crash rates stay lower than many Windows boxes at the same price, which matters for unattended gateways.

If you are turning this checklist into a “installed Saturday, online Monday” agent host, Mac mini M4 is a strong value starting point—get one now and run Hermes on hardware built for always-on work.