2026 Hermes Agent Complete Install & Configuration Guide: Step-by-Step Hands-On Tutorial from Zero to Running

2. Where most guides fall short

1. The ceiling: “startup succeeded.” A welcome banner in the terminal does not mean the model is reachable, file tools work, or a gateway can receive messages. Hermes is truly usable only after environment checks, model connectivity, permission boundaries, traceable logs, and a low-risk case acceptance pass.
2. Hidden cost: keys and paths scattered everywhere. API keys live only in notes; config.yaml and .env disagree; the workspace points at your entire home directory—one misstep can rewrite SSH keys or a production repo.
3. Stability & audit: install-and-forget where logs live. When something breaks, blind reinstalls wipe the only clues in ~/.hermes/logs/errors.log; without backups you cannot roll config back after an upgrade.

3. Pre-install prep: Mac & environment checklist

Goal: avoid discovering network, Git, or disk issues halfway through install. Pass criterion: every item below checked before running the install script.

• System: macOS 12+ (Intel or Apple Silicon; Apple Silicon gives more local-inference options, but cloud models still follow each provider’s docs).
• Git: the official git installer’s only hard prerequisite is Git (git --version ≥ 2.30 recommended). Without Git, install Xcode Command Line Tools or brew install git first.
• Network: must reach GitHub raw (install script) and your chosen LLM provider API; set HTTPS_PROXY early in corporate proxy environments.
• Disk: the official install pulls Python 3.11, Node.js v22, ripgrep, ffmpeg, and the repo—reserve ≥ 2GB free (closer to 1.5–3GB with Skills cache; follow current docs).
• Permissions: per-user install needs no sudo; if you ever installed as root, data may live under /root/.hermes, not the paths used here.
• Backup: if an old ~/.hermes exists, run cp -a ~/.hermes ~/.hermes.bak-$(date +%F) first.
• Test directory: create an isolated workspace (we use ~/hermes-lab throughout). Do not point your first case at ~/Documents, production git repos, or directories with secrets.

# Quick pre-install self-check (copy and run)
git --version
sw_vers
df -h ~
mkdir -p ~/hermes-lab/{inbox,outbox,archive}
echo "Hermes lab sample: Q2 planning notes." > ~/hermes-lab/inbox/sample.txt

If it fails, check: Git errors → CLT/Homebrew; low disk → clear Downloads or use another volume; network timeout → switch network or mirror—do not reinstall three times without knowing why.

4. Official Hermes Agent installation

Goal: use Nous Research’s maintained installer so Python, Node, and the CLI are handled for you. Source: official Installation docs (re-check for new version numbers or extra flags before you publish).

4.1 Recommended: git one-line install (tracks main)

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The installer automatically sets up uv, Python 3.11, Node.js v22, ripgrep, ffmpeg, clones the repo, creates a venv, and adds hermes to PATH. Typical per-user layout:

• Code: ~/.hermes/hermes-agent/
• Data & config: ~/.hermes/ (override with HERMES_HOME)
• CLI: ~/.local/bin/hermes

4.2 Alternative: pip install (requires Python 3.11+ already)

pip install hermes-agent
hermes postinstall   # optional: Node, browser, ripgrep, ffmpeg + setup

PyPI tracks tagged releases; for bleeding edge, prefer the git install script above. hermes update behaves differently per install method—trust what hermes doctor reports.

4.3 Three must-dos after install

source ~/.zshrc          # or open a new terminal window
hermes version           # note the version for future troubleshooting
hermes doctor            # auto-diagnose gaps; add --fix to attempt repairs

Pass criterion: which hermes points to ~/.local/bin/hermes; hermes doctor has no blocking FAIL. If it fails, check: last 20 lines of install log → PATH → whether you invoked the repo’s raw hermes with system Python (use the venv launcher).

Do not: delete ~/.hermes and reinstall immediately on failure—save terminal output and hermes doctor first, or you cannot tell network issues from permission issues.

5. Configure models & API keys

Goal: let Hermes call your chosen LLM provider. Pass criterion: non-interactive smoke test returns a sensible reply; hermes auth list or .env has the entry and the key is not left in shell history in plain text.

5.1 Interactive setup (recommended first time)

hermes setup          # full wizard: models, tools, gateway, etc.
# or step by step:
hermes model          # pick provider and default model
hermes tools          # enable tool sets as needed

5.2 Environment variables & config files

Main config usually lives at ~/.hermes/config.yaml; secrets are referenced in ~/.hermes/.env (confirm with hermes config path and hermes config env-path). Example (variable names follow your provider’s current docs—do not copy stale names):

# Example: OpenRouter (replace with your key; never commit to git)
hermes config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# or edit .env directly (chmod 600 ~/.hermes/.env)
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.hermes/.env

Boundary note: model pricing, API limits, regional availability, and privacy policies change with providers—read their latest terms before production use. This article does not lock you to one model name.

6. Workspace, permissions & logs

Goal: after install, make operations traceable, bounded, and rollback-friendly. Principle: least privilege—allow only the test directory first, then gradually open real projects.

• Workspace: set ~/hermes-lab in config.yaml or the session; add AGENTS.md there describing allowed tools and boundaries (see official Context Files docs).
• macOS permissions: terminal/file tools may prompt for Full Disk Access—during first acceptance, grant only what the test directory needs, not whole-disk access.
• Log directory: default ~/.hermes/logs/ (agent.log, errors.log, gateway.log). Inspect with hermes logs list, hermes logs errors --since 30m.
• Secret hygiene: chmod 600 ~/.hermes/.env; do not put backup zips in sync folders; never let the Agent read ~/.ssh, payment data, or production kubeconfig.
• Background run (optional): for Telegram/Discord gateways, use hermes gateway setup and hermes gateway install; long-term ops are covered in our Hermes long-term maintenance guide.

Pass criterion: after telling the Agent “read/write only ~/hermes-lab”, attempts outside the home test paths are denied or logged for audit.

7. First-run acceptance: seven-step runbook

These seven steps push from “configuration complete” to “production-ready”—run them as written and keep screenshots or log snippets.

1. Diagnose: hermes doctor --fix → no unresolved FAIL.
2. Model ping: hermes chat -q "Reply with exactly: HERMES_OK" → reply contains HERMES_OK.
3. File read: have the Agent read ~/hermes-lab/inbox/sample.txt and repeat the first sentence.
4. File write: write ~/hermes-lab/outbox/ping.txt → visible with cat.
5. Logs: hermes logs errors --since 10m → no new ERROR (or known benign items documented).
6. Close terminal: quit the window, open a new one, repeat step 2 → rules out PATH valid only in the current session.
7. Optional reboot: restart the Mac and rerun step 2 (if gateway is installed, add hermes gateway status).

Reference thresholds (personal acceptance, not an official SLA): smoke reply < 60s; 0 unexplained ERROR lines in errors.log in 10 minutes; after a test write, ls -la ~/hermes-lab/outbox shows the new file.

8. First hands-on case: summary + todos + rollback-ready output

Scenario: read sample text in the test directory, produce an English summary and three todos, write Markdown output, and keep a rollback copy. This case covers install outcome (CLI), configuration outcome (model), and a real workflow (read → reason → write → logs).

# 1. Prepare input (skip if Section 3 already created it)
cat > ~/hermes-lab/inbox/weekly-notes.txt <<'EOF'
This week: finished draft Hermes install documentation.
Follow-ups: configure OpenRouter budget alerts; evaluate Telegram gateway next week.
Risk: never commit API keys to git.
EOF

# 2. Start an interactive session (or use one compound instruction)
hermes
# In session, send (example prompt):
# "Use only the ~/hermes-lab directory. Read inbox/weekly-notes.txt,
#   write a summary under 150 words plus 3 todos in English,
#   save to outbox/summary-and-todos.md,
#   and copy the original file to archive/weekly-notes.bak"

# 3. Non-interactive verification
ls -la ~/hermes-lab/outbox/summary-and-todos.md
ls -la ~/hermes-lab/archive/
hermes logs agent -n 30 --since 15m

Pass criteria:

• summary-and-todos.md contains a summary and three todos consistent with the source file.
• archive/ holds a backup you can diff against.
• Logs show matching tool calls; provider billing/dashboard reflects this run (helps verify cost).

Rollback: rm ~/hermes-lab/outbox/summary-and-todos.md && cp ~/hermes-lab/archive/weekly-notes.bak ~/hermes-lab/inbox/weekly-notes.txt. If it fails, check: model truncated the file → permission denied on outbox → tool errors in errors.log.

9. Troubleshooting: layer by layer, avoid blind reinstalls

Pre-publish fact checklist (maintainers): official install.sh URL, minimum macOS, default directory names, CLI subcommands, provider env var names, log paths—update the doc before shipping if any change. Readers only need to remember: on error, run hermes doctor, then read errors.log, and only then consider reinstalling.

10. Next steps: from test directory to real workflows

After acceptance passes, expand in this order—do not jump straight to production repos or payment systems:

1. Add one real side-project directory to the allowlist; still block ~/.ssh and global * read/write.
2. Enable hermes cron for daily low-risk tasks (e.g. inventory Downloads—still scoped to test dirs).
3. Configure one messaging gateway (Telegram/Discord) with pairing mode to block strangers (see official Security docs).
4. Establish a weekly hermes backup --quick rhythm, then read the long-term maintenance guide for upgrade and rollback drills.