Hermes Agent Install Guide (2026 Complete Edition)

System requirements

Hermes Agent v2026.9.14 needs an environment that can run Python 3.10+ and Node.js 18+. Most dev machines from 2020 onward qualify out of the box.

• OS: macOS 12+ (Intel/Apple Silicon), Ubuntu 20.04+, Debian 11+, Fedora 36+, Arch, or WSL2 Ubuntu
• Python 3.10+ (the installer auto-installs pyenv and a Python build if missing)
• Node.js 18+ (also auto-installed)
• Git 2.30+ (for cloning the Skills registry)
• Disk: 1.5 GB including the Skills cache
• Network: GitHub raw and your chosen LLM provider API must be reachable

If anything is missing, hermes doctor flags the exact item with a fix at the end of install.

One-line install (Mac + Linux)

Paste this in a terminal. The installer handles Python, Node.js, dependencies, the Hermes CLI, and PATH wiring.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

1. What it does

   Checks Python/Node versions → installs to ~/.hermes → adds hermes to PATH → pulls the default nous/core Skills registry → prints the binary path.

2. When it finishes

   When you see ✅ Hermes Agent installed at ~/.hermes the main flow is done. End-to-end takes 1-3 minutes depending on network.

3. Activate PATH

   Open a new terminal window, or run source ~/.zshrc (default macOS) / source ~/.bashrc (most Linux) in the current shell.

Then run hermes setup for interactive provider config, and hermes to launch the agent. Next section covers details.

Windows users

Hermes Agent supports native Windows 10/11 installation through PowerShell. Use `iex (irm https://hermes-agent.nousresearch.com/install.ps1)` for the native path, or choose WSL2 when you prefer a full Linux environment.

• Win10 21H2 and Win11 ship with WSL2; enabling it takes about 5 minutes
• Recommended distro: Ubuntu 22.04 LTS from the Microsoft Store
• After WSL Ubuntu is up, run the install.sh from the previous section inside the Ubuntu terminal
• VS Code Remote-WSL extension lets you edit WSL projects from Windows seamlessly

Full walkthrough including 8 common WSL errors lives at /en/install/windows.

Verify install: hermes doctor

A single command self-checks 12 items: Python/Node versions, PATH, Skills registry connectivity, LLM provider, disk, file permissions.

hermes doctor

• ✅ pass — nothing to do
• ⚠️ warn — non-blocking, may affect advanced usage later
• ❌ block — must be fixed
• Add --verbose for detailed diagnostics; --fix attempts auto-repair where safe

See /en/cli/doctor for the full mapping of all 12 checks and their error codes.

5 things to do after install

Install is not the finish line. These five steps take you from "it starts" to "it actually works".

1. 1. Configure an LLM provider (required)

   Run hermes setup for the interactive wizard. Pick whichever provider you have access to: Claude, OpenAI, OpenRouter, Zhipu GLM, Kimi, etc. See /en/providers/glm and /en/providers/kimi for region-specific notes.

2. 2. Run your first agent task

   Type hermes in a terminal and ask it something like "list every Python file in the current directory by line count". This proves the LLM round-trip works.

3. 3. Install commonly used Skills

   hermes skills install code-review installs a code review Skill; hermes skills list shows what is installed. The bundled catalog and Skills Hub provide bundled and hub-distributed Skills.

4. 4. Enable Memory (optional but recommended)

   By default Hermes is stateless. Memory makes it remember your preferences and project structure across sessions. hermes config memory enable + hermes memory init.

5. 5. Connect a messaging platform (optional)

   DingTalk, Feishu, and Slack can be wired through Hermes Gateway for team-wide deployment. See /en/integrations/dingtalk and /en/integrations/feishu.

Common install errors

90% of install failures fall into one of these six buckets. Match the symptom and apply the fix.

• curl: (60) SSL certificate problem

  原因 / Cause: System CA certificates are expired or a proxy/firewall is intercepting (common on corporate networks).

  修复 / Fix: Run sudo apt-get install ca-certificates or brew install openssl to refresh the trust store. If still failing, ask your network admin to allow raw.githubusercontent.com.

• Python: command not found

  原因 / Cause: macOS 12+ no longer ships python (only python3). The installer auto-installs pyenv but requires a fresh terminal.

  修复 / Fix: Close the current terminal and open a new one, or source ~/.zshrc in the current session.

• EACCES: permission denied while writing to /usr/local

  原因 / Cause: On Linux the script tried to symlink hermes into /usr/local/bin but the current user lacks permission.

  修复 / Fix: Do NOT run the installer with sudo — it installs to ~/.hermes and does not need root. If you ran sudo by accident, sudo rm -rf ~/.hermes && rm -rf /usr/local/bin/hermes and re-run as a normal user.

• WSL2 install hangs at "Installing Python deps"

  原因 / Cause: WSL2 uses the Windows host for DNS by default; pypi.org sometimes flakes on certain networks.

  修复 / Fix: In WSL Ubuntu: echo "[network]\ngenerateResolvConf = false" | sudo tee /etc/wsl.conf, then wsl --shutdown and restart, then set /etc/resolv.conf manually to 8.8.8.8.

• hermes: command not found (right after install)

  原因 / Cause: PATH not loaded. The installer wrote to ~/.zshrc or ~/.bashrc but the current shell has not reloaded.

  修复 / Fix: Run source ~/.zshrc (default macOS) or source ~/.bashrc (most Linux), or open a new terminal.

• hermes doctor reports "Skills registry unreachable"

  原因 / Cause: GitHub raw blocked or DNS poisoned in your network.

  修复 / Fix: Set HTTPS_PROXY to your local proxy and re-run hermes skills sync, or configure skills.mirror in hermes config to a community mirror.

Uninstall

Everything lives under ~/.hermes; one command removes it all.

rm -rf ~/.hermes && unlink $(which hermes) 2>/dev/null

• The export PATH line in ~/.zshrc / ~/.bashrc added at install time can be removed manually
• LLM provider API keys live in ~/.hermes/config.toml — back up before deleting if you want to keep them
• All installed Skills are under ~/.hermes/skills and will be removed too

Update to the latest

Day-to-day upgrade is one command; details (pinning, rollback, beta channel) live at /en/cli/update.

hermes update

• Default: upgrade to the latest Stable release
• hermes update --version v2026.9.14 to pin a specific version
• hermes update --rollback to revert to the previous version on this machine
• hermes update --channel beta to opt into the beta channel

Before upgrading, Hermes auto-backs up ~/.hermes/config.toml to ~/.hermes/backups/, so configs are safe.