How to install Hermes Agent

TL;DR — Hermes Agent installs with a single curl command on macOS, Linux, or Windows via WSL2. The installer takes two to three minutes end-to-end and is maintained in lockstep with the main repo. This guide covers Hermes Agent v0.10.0 (current release as of April 2026; 112,074 GitHub stars as of 2026-04-23).

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 — two options. WSL2 with Ubuntu or Debian inside is the road-tested path. Native Windows works via an early-beta PowerShell installer (Nous's wording: "not road-tested as broadly"). See Install on Windows below.
• Termux (Android) — supported via a curated .[termux] extra. The same curl one-liner works inside Termux; voice dependencies are excluded.

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, ripgrep, ffmpeg, the venv, the global hermes command, and the ~/.hermes/ directory tree. On native Windows it additionally bundles a portable Git Bash (~45 MB MinGit) inside %LOCALAPPDATA%\hermes\git.

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

Two supported paths. WSL2 is the road-tested option that most users should pick. Native Windows via PowerShell is shipped as an early beta in the official installer — Nous's wording is "not road-tested as broadly" — and is the right call if you can't or won't enable WSL.

Option A — WSL2 (recommended)

WSL2 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.

Option B — Native Windows via PowerShell (early beta)

Open PowerShell (not WSL, not cmd) and run:

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

The installer drops Hermes into %LOCALAPPDATA%\hermes and unpacks a portable Git Bash (~45 MB MinGit) into %LOCALAPPDATA%\hermes\git so shell-based tools work without a system-wide Git install. It also sets up uv, Python 3.11, Node.js, ripgrep, and ffmpeg in the same directory.

After the script finishes, close and reopen PowerShell so hermes is on PATH, then:

hermes version
hermes doctor

What "early beta" actually means. The Nous team's own framing in the README: "not road-tested as broadly" as the Linux/macOS path. Expect more rough edges in the messaging gateway and any tool that shells out to native binaries. If something breaks and you have the option, WSL2 is the safer fallback.

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", "cannot execute", or curl errors

You ran the Linux curl ... | bash command from PowerShell or cmd. That path is for WSL only. Either open your Ubuntu (WSL) terminal and rerun the bash installer, or use the native PowerShell installer instead: irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex.

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

Get the ecosystem inside your agent

Install the hermes-atlas MCP server so Claude Desktop, Cursor, Claude Code, or any MCP-aware client can search the catalog, fetch project summaries, and answer free-form questions about the Hermes ecosystem mid-chat. Five tools: search_projects, get_project, list_by_category, get_guide, ask_atlas.

Recommended — one command

Run this in a terminal. The installer detects your OS, finds the right config file for your client, and safely merges in the hermes-atlas entry without touching anything else:

npx -y hermes-atlas-mcp install --client claude-desktop

Replace claude-desktop with cursor or claude-code as needed. Add --print first if you want to preview the exact diff without writing anything.

Then fully quit and reopen the client — closing the window isn't enough, the whole process has to restart. In a new chat, click the tool icon (usually at the bottom of the message box) and you'll see the five tools listed.

To remove later:

npx -y hermes-atlas-mcp uninstall --client claude-desktop

Manual install — Claude Desktop

If you'd rather edit the config yourself, or the installer doesn't work on your setup, here's the full walkthrough.

Step 1 — open the config file

The easiest way is through Claude Desktop's built-in button:

1. Open Claude Desktop.
2. Click the Settings gear (or Cmd/Ctrl+,).
3. Select the Developer tab on the left.
4. Click the Edit Config button. The file opens in your default text editor.

If you'd rather find it by path:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json (usually C:\Users\YOU\AppData\Roaming\Claude\claude_desktop_config.json)
• Linux: ~/.config/Claude/claude_desktop_config.json

Step 2 — add the hermes-atlas entry

If the file is empty, or doesn't exist, paste this as the full contents:

{
  "mcpServers": {
    "hermes-atlas": {
      "command": "npx",
      "args": ["-y", "hermes-atlas-mcp"]
    }
  }
}

If the file already has content, merge the new entry into the existing mcpServers block. For example, if your file currently looks like this:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}

...change it to this (add a comma after the filesystem block, then the new hermes-atlas object):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    },
    "hermes-atlas": {
      "command": "npx",
      "args": ["-y", "hermes-atlas-mcp"]
    }
  }
}

If the file has top-level settings like preferences or anything other than mcpServers, leave those alone — only merge into the mcpServers object (or add it if it doesn't exist yet).

Step 3 — save and fully restart Claude Desktop

Save the file. Then fully quit Claude Desktop — closing the window isn't enough, the background process has to restart.

• macOS: Cmd+Q with Claude Desktop focused, or right-click the dock icon → Quit.
• Windows: File → Exit, or right-click the taskbar icon → Close window, or kill it in Task Manager if a Claude process lingers.

Reopen Claude Desktop normally.

Step 4 — verify

Start a new chat. Click the tool / attachment icon at the bottom of the message box. You should see five tools listed under hermes-atlas:

• search_projects
• get_project
• list_by_category
• get_guide
• ask_atlas

If they're missing, most-likely causes in order:

1. You didn't fully quit Claude Desktop. Quit and reopen again.
2. The JSON isn't valid (a missing comma, extra trailing comma, unbalanced brace). Paste the file into any online JSON validator.
3. You don't have Node.js installed (the npx command needs it). Install from nodejs.org — any LTS version works.

Manual install — Cursor

File: ~/.cursor/mcp.json (global, applies to every project) or .cursor/mcp.json at your project root (per-project). Use the same JSON shape as Claude Desktop above. Restart Cursor.

Manual install — Claude Code

Easiest: inside a Claude Code session, run /mcp — the built-in UI walks you through adding a server without touching any file. Otherwise, edit ~/.claude.json using the same shape.

Continue, Windsurf, Zed, other MCP clients

Any MCP-compatible client works the same way. Configure a server named hermes-atlas that runs npx -y hermes-atlas-mcp via stdio. The client docs will point you at the right config file.

Source: github.com/ksimback/hermes-atlas-mcp · npm. MIT-licensed, experimental (0.x), batch releases weekly.

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?

Yes, in early beta. As of v0.10.0, Nous ships a native Windows installer you run from PowerShell: irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex. It installs to %LOCALAPPDATA%\hermes and bundles a portable Git Bash. Nous explicitly flags this path as "not road-tested as broadly" — for production use, prefer WSL2: wsl --install in PowerShell, install Ubuntu, then run the standard curl installer from inside WSL.

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.