How to install Hermes Agent

Covers Hermes Agent v0.10.0 (current release as of April 2026). The installer is updated in lockstep with the main repo — 112,074 GitHub stars as of 2026-04-23 — so the commands below track the latest release without manual edits.

TL;DR

One curl command. Two to three minutes. Works on macOS, Linux, and Windows via WSL2.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc   # or: source ~/.zshrc
hermes             # start chatting

If that worked, skip to first run and model provider. If it didn't, the troubleshooting tree covers the nine failure modes I've seen, in the order you should check them.

Before you start

Supported OSes (as of v0.10.0):

• macOS 13 Ventura or newer. Apple Silicon (M1/M2/M3/M4) and Intel both supported. Apple Silicon is faster for local-model workloads.
• Linux — Ubuntu 22.04 or newer, Debian 12, Fedora 39+, Arch rolling. Any modern distro with glibc 2.35+ should work.
• Windows — only via WSL2 with an Ubuntu or Debian distro inside. Bare Windows is not supported; see Install on Windows below.

Prerequisites — Hermes's installer is aggressive about setting up its own stack, so you need almost nothing pre-installed:

• Git — only hard requirement.
• A terminal — bash, zsh, and fish all work.
• ~200 MB of disk for the install itself; budget another 100–500 MB for memory, skills, and session logs as you use it.
• Model access (optional on first install, required before useful work) — an API key from Anthropic / OpenAI / z.AI / MiniMax / DeepSeek, or a Nous Portal subscription, or a local model via Ollama / LM Studio.

The installer handles the rest automatically: uv, Python 3.11, Node.js 22, ripgrep, ffmpeg, the venv, the global hermes command, and the ~/.hermes/ directory tree.

Install on macOS

Open Terminal (or iTerm, or Warp — any shell). Run:

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

Reload your shell so hermes is on PATH:

source ~/.zshrc   # macOS default since Catalina
# or: source ~/.bashrc if you switched to bash

Test it:

hermes version

Apple Silicon (M1/M2/M3/M4) notes

The installer auto-detects arm64 and pulls native binaries. No Rosetta required. If you already have Homebrew installed, the installer uses it to pull missing dependencies — otherwise it installs Homebrew for you (and prints what it's doing).

Intel Mac notes

Everything works identically. The only caveat: local-model inference via Ollama is meaningfully slower than Apple Silicon — budget a frontier API key (Anthropic, OpenAI, GLM) for real work.

Install on Linux

The command is identical across distros:

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

Distro-specific notes

• Ubuntu 22.04 / 24.04, Debian 12 — works out of the box. If you're on a fresh minimal cloud image, apt-get install -y git curl first.
• Fedora 39+ — identical. Uses dnf under the hood for any missing system packages.
• Arch / Manjaro — works; installer uses pacman for missing deps. The AUR has a community hermes-agent package too, but the official curl installer is what the Nous team ships against.
• Alpine — works with caveats. glibc is required; the installer will fall back to a statically-linked path, but memory and skills with native deps (ffmpeg audio handling, image cache) can be flaky. A $5 Debian VPS is the path of least resistance.

Install on Windows (via WSL2)

Bare Windows is not supported. The Hermes team has stated no plans for a native Windows port — Nous's official position is that agent workloads belong on a Unix userland. Use WSL2, which runs a real Linux kernel inside Windows 11 with near-native performance.

1. Install WSL2

Open PowerShell as Administrator:

wsl --install

This installs WSL2 + Ubuntu by default. Reboot when prompted. On first boot of Ubuntu, create a username and password.

2. Install Hermes inside WSL

Open the Ubuntu terminal (from Start Menu) and run the same Linux install command:

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

3. Use Windows Terminal

The default WSL console is workable but Windows Terminal (free, Microsoft Store) is substantially better — tabs, font control, and proper Unicode. Set Ubuntu as your default profile and you're done.

Verify the install

Run these three commands. All three should return clean output:

hermes version      # prints v0.10.0 (or newer)
hermes doctor       # system health check — every line should be green
hermes status       # current config + running daemons

For a live smoke test that exercises the model layer (skip this until you've configured a provider — see below):

hermes chat -q "Hello! What tools do you have available?"

You should see a short response plus a list of enabled tools. If this hangs, the model provider isn't reachable — jump to first run and model provider.

First run and model provider

Run hermes with no arguments on a fresh install to trigger the interactive setup:

hermes

Hermes walks you through provider selection. Pick one of these four paths:

Path 1 — Nous Portal (easiest)

Nous Portal is a single subscription that routes across Claude, GPT, GLM, MiniMax, Nous's own models, and many more via one auth. Sign in with OAuth from the CLI when prompted. One flat monthly bill, no key management. Most people end up here eventually.

Path 2 — Bring your own API key

Paste a key from Anthropic (sk-ant-...), OpenAI (sk-...), z.AI, MiniMax, or DeepSeek when prompted. You can swap later with hermes model.

Path 3 — Local model via Ollama

Install Ollama first (ollama.com), pull a tool-calling-capable model (Qwen 2.5 Coder 32B is the community favorite), then point Hermes at it. Local models are great for coding and chat but weaker at multi-step tool chains — the full tradeoff is in chapter 5 of the handbook.

Path 4 — Skip for now

You can install Hermes without configuring a model and wire one up later with hermes model. Useful if you're installing on a VPS and want to set up the Telegram gateway first.

Troubleshooting common install errors

Check these in order. The top three catch about 90% of failures.

1. "Command not found: hermes"

Your shell didn't pick up the new PATH. Open a fresh terminal window, or run source ~/.bashrc (or ~/.zshrc, or ~/.config/fish/config.fish for fish). If that still doesn't work, check that ~/.hermes/bin is in your PATH: echo $PATH | tr ':' '\n' | grep hermes.

2. "Provider error: invalid API key"

Trailing whitespace is the #1 cause. Paste with care, or use the heredoc approach: hermes config set model.api_key "$(cat)" then paste and hit Ctrl-D. Second most common cause: wrong provider selected for the key type.

3. Windows: "bad interpreter" or "cannot execute"

You're running Hermes from bare Windows cmd or PowerShell, not from inside WSL. Open your Ubuntu (WSL) terminal and rerun from there.

4. "Permission denied" during install

Usually caused by running the curl command under sudo. Don't. Hermes installs per-user under ~/.hermes/ and doesn't need root. If you already ran it as root, sudo rm -rf ~/.hermes/ /root/.hermes/ and retry as your normal user.

5. "uv: command not found" mid-install

The installer failed between installing uv and using it — usually because a previous interrupted run left a half-configured state. Simply re-run the install command; it's idempotent.

6. Python version mismatch

You have Python 3.9 or older in PATH and something is resolving to that first. The installer pins Python 3.11 in its own venv, but if you see a version error, drop to the manual install below, which gives you explicit control.

7. npm errors ("ENOENT", "EACCES")

Node.js didn't install cleanly. Delete ~/.hermes/, reinstall Node via your OS package manager (brew install node on Mac, apt install nodejs npm on Ubuntu), then rerun the Hermes curl installer.

8. ffmpeg / ripgrep missing (macOS Apple Silicon)

Homebrew path mismatch — Apple Silicon's Homebrew lives at /opt/homebrew/bin, not /usr/local/bin. Add eval "$(/opt/homebrew/bin/brew shellenv)" to your ~/.zshrc and rerun.

9. Installer hangs downloading the hermes binary

GitHub release download from a rate-limited or corporate-firewalled network. Set export GITHUB_TOKEN=... (any personal access token) before rerunning, or use the manual install.

Manual installation

When the curl installer fails and you want step-by-step control:

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# create venv + install Python deps
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"
uv pip install -e ".[all]"

# install Node dependencies
npm install

# create the hermes directory tree
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env

# symlink hermes to ~/.local/bin for PATH convenience
ln -s "$(pwd)/bin/hermes" ~/.local/bin/hermes

Add ~/.local/bin to your PATH if it isn't already. Verify with hermes version.

Uninstall or clean reinstall

Complete uninstall — removes everything including memory, skills, and config:

rm -rf ~/.hermes/

Reset config but keep memory and skills:

hermes config reset

Clean reinstall — useful when something is wedged:

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

What to do next

You're installed. The next three handbook chapters walk you through the mistakes most people make on day one:

• Pick your model — where most first setups silently fail. Don't use Gemma or Llama 8B for agent work.
• Your first workflow — three concrete examples (coding assistant, Telegram bot, cron automation). Pick one and ship it today.
• Essential skills to install first — five community skills that should be on every Hermes install on day one.

FAQ

Does Hermes Agent work on bare Windows?

No. Bare Windows is not officially supported as of v0.10.0. Use WSL2 — wsl --install in PowerShell, install Ubuntu, then run the standard curl installer from inside WSL. Performance is effectively native.

Does Hermes work on Apple Silicon (M1, M2, M3, M4)?

Yes, natively. Apple Silicon is a first-class target. The installer detects arm64 and pulls native binaries. No Rosetta required.

Can I run Hermes Agent on a Raspberry Pi or low-end VPS?

Yes. Hermes itself runs comfortably on a $5 VPS (1 CPU, 1 GB RAM) or a Raspberry Pi 4/5 with 4+ GB RAM. The practical constraint is not Hermes but the model — pair it with a hosted API (Nous Portal, Anthropic) and the agent host stays lightweight.

How much disk space does Hermes Agent use?

About 200 MB for a fresh install. Memory, skills, and session logs accumulate in ~/.hermes/ over time — budget another 100–500 MB depending on how heavily you use it.

Can I run Hermes Agent fully offline?

Yes. Install Hermes, pair it with Ollama or LM Studio, disconnect the network. Memory, skills, cron, and file tools all work offline. Local models are weaker at multi-step tool chains, so complex workflows may degrade — but single-shot chat and coding work fine.

Do I need Docker to install Hermes?

No. The official installer is a native binary install; Docker is not required. Community-maintained Docker images exist (browse the deployment options list on Hermes Atlas) if you prefer containerized deploys, but the path of least resistance is the curl installer.

What if the curl install fails mid-way?

Re-running the same curl command is safe — the installer is idempotent. If it fails a second time, fall back to the manual install above.