How to install Hermes Agent (Nous Research) on Linux, Windows, and Mac (2026)

July 23, 20266 minHermes Agent, Nous Research, AI, Agents, Tutorial

Short answer (60 seconds): Hermes Agent installs with one command. On Linux / macOS / WSL2 / Android (Termux): curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash. On native Windows (PowerShell): iex (irm https://hermes-agent.nousresearch.com/install.ps1). On macOS/Windows with GUI: download the Hermes Desktop installer from the official site. The script installs uv, Python 3.11, Node v22, ripgrep, and ffmpeg automatically — the only prerequisites on Linux are git, curl, and xz-utils. Takes between 60 seconds (modern laptop) and 4 minutes (older hardware). Verify with hermes --version and hermes doctor.

Hermes Agent is an open-source AI agent from Nous Research. Unlike hosted chatbots, it runs locally on your machine, connects to 300+ models via Nous Portal, and exposes extensible skills, sessions, and a tool gateway.

This post is the guide I wish I'd had the first time I tried it. It covers the official paths (pure CLI, Desktop GUI, install without sudo), the prerequisites the script handles on its own (and the few it doesn't), and post-install verification. Let's go through it.

Before you start: what you need

Requirement	Detail
OS	Linux, macOS, WSL2, Android (Termux), or Windows 10+ native
Privileges	Normal user. Works without sudo with graceful degradation
Internet connection	Script downloads Node, Python, ripgrep, ffmpeg, repo
Time	60–240 seconds depending on hardware and connection
Knowledge	Basic terminal. Nothing about venv or manual configuration

The only thing you need preinstalled on Linux: git, curl, and xz-utils. On Debian/Ubuntu: sudo apt install curl xz-utils git. For the desktop app, also build-essential: sudo apt install build-essential.

Path 1 · Hermes Desktop (macOS / Windows with GUI)

If you want the GUI with tray icon, integrated chat system, and in-app update, download the installer from hermes-agent.nousresearch.com and run the .dmg (macOS) or .exe (Windows). The installer downloads CLI + UI + dependencies and leaves everything ready.

After installing, open Hermes Desktop and run the setup wizard, or use the shortcut:

hermes setup --portal   # Nous Portal: 300+ models with one subscription

Path 2 · CLI only (Linux, macOS, WSL2, Android, Windows)

If you prefer pure CLI or you're on Linux, this is the path. One line:

On Linux / macOS / WSL2 / Android (Termux)

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

On native Windows (PowerShell)

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

After installing, reload the shell:

source ~/.bashrc   # or: source ~/.zshrc
hermes             # start the agent

If you later want to add the GUI from a CLI install:

hermes desktop

What the installer does exactly

Detects the OS and user mode (per-user or root).
Verifies prerequisites: git (always), curl + xz-utils on Linux.
Installs any missing deps: uv (Python package manager), Python 3.11, Node.js v22, ripgrep, ffmpeg.
Clones the repo to ~/.hermes/hermes-agent/ (per-user) or /usr/local/lib/hermes-agent/ (root).
Creates the Python virtualenv.
Symlinks ~/.local/bin/hermes → venv launcher (per-user) or /usr/local/bin/hermes (root).
Launches the hermes setup wizard or the --portal shortcut if requested.

Final per-user layout:

# File structure after per-user install
~/.hermes/
  hermes-agent/          # repo checkout
  config.yaml            # agent config
  auth.json              # provider credentials
  venvs/                 # Python virtualenvs
~/.local/bin/hermes      # binary symlink

Path 3 · Install without sudo (system service users)

If you'll run Hermes as a service account (without sudo), the installer detects the lack of sudo and degrades: it skips the Playwright --with-deps step (which needs to install system libraries via apt) and downloads Chromium to the user's local cache.

Recommended split (Debian/Ubuntu):

Once, as admin with sudo, install the system libraries Chromium needs:

sudo npx playwright install-deps chromium

As service user without sudo, run the normal installer — it detects the lack of sudo and degrades:

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

Add hermes to the service user's PATH (service accounts often have a minimal PATH):

# Option A — add to service user's profile
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# Option B — symlink system-wide (as admin)
sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes

Verify: hermes doctor should run cleanly.

If you don't need browser automation (running Hermes headless), you can skip the Playwright step:

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

Configure the LLM provider

After installing, the next step is deciding how to connect the model. There are two paths.

Fast path · Nous Portal

A single subscription gives you access to 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser):

hermes setup --portal

Manual path · Your own provider

If you prefer OpenAI / Anthropic / OpenRouter direct:

hermes model                    # choose provider and model
hermes config set OPENAI_API_KEY sk-...
# or:
hermes config set ANTHROPIC_API_KEY sk-ant-...
# or:
hermes config set OPENROUTER_API_KEY sk-or-...

Then enable the tools you'll use:

hermes tools                    # tools toggle (browser, file ops, etc.)
hermes gateway setup            # configure channels (Telegram, Discord, etc.)

Verify it installed correctly

Two main commands, plus some complements.

hermes --version       # binary version
hermes doctor          # full check: config, deps, service health
hermes config check    # config migration status

doctor automatically detects the install method (git, Docker, NixOS) and shows the matching update command. If it reports missing items, it prints them with the exact fix.

Quick troubleshooting

Problem	Solution
`hermes: command not found`	`source ~/.bashrc` or `source ~/.zshrc`. If you still don't see it, add `~/.local/bin` to PATH.
`API key not set`	`hermes model` or `hermes config set OPENROUTER_API_KEY your_key`.
Missing config after update	`hermes config check` then `hermes config migrate`.
`ModuleNotFoundError: No module named 'dotenv'`	You're invoking the source file instead of the venv launcher. Verify `~/.local/bin/hermes` points to `venv/bin/hermes`.
No sudo and Playwright fails	Run `sudo npx playwright install-deps chromium` once as admin, or pass `--skip-browser` to the installer.
Update doesn't finish on Windows	Close Hermes Desktop and any open REPLs, then `hermes update` again.

After installing: first steps

Once hermes doctor passes green, you can start chatting:

hermes               # start the chat
hermes agent "..."   # one-shot: send it a task and exit
hermes gateway start # leave the gateway running in background

If you want the gateway as a managed service (systemd on Linux, launchd on macOS, Scheduled Task on Windows), hermes setup configures it or you can do it manually with hermes gateway install.

Want to discuss your specific case before investing time configuring it? There's a CTA at the end with a free 30-minute call.

Frequently asked questions

What is Hermes Agent in one sentence?

An open-source AI agent from Nous Research with CLI, desktop app, and tool gateway. A single `hermes` binary that runs on your machine, connects to 300+ models via Nous Portal (or your chosen provider), and exposes extensible skills, sessions, and tools.

Do I need to install Python, Node, or ffmpeg manually?

No. The Hermes installer detects what's missing and downloads it automatically: uv, Python 3.11, Node.js v22, ripgrep, and ffmpeg. The only prerequisite on Linux is `git`, `curl`, and `xz-utils`. On native Windows, the PowerShell installer downloads everything too.

What's the difference between installing Hermes Desktop and CLI only?

Hermes Desktop (GUI) is available as a native installer for macOS and Windows — it ships the bundle with CLI + UI. On Linux/WSL2/Android only the CLI is available; if you want the GUI later, run `hermes desktop` and Hermes will launch it.

Does it work on a server without GUI or sudo?

Yes. Hermes detects whether sudo is available and degrades gracefully — it skips the `--with-deps` Playwright step (the only thing that truly needs root). If you'll use browser automation, an admin runs `sudo npx playwright install-deps chromium` once and that's it.

How long does the installation take?

Between 60 and 180 seconds on a modern laptop — slower if the installer has to download Node and Python. On older hardware it can reach 4 minutes. Includes downloading deps, cloning the repo, creating the venv, and putting `hermes` on the PATH.

How do I verify the install worked?

Two commands: `hermes --version` (returns the version) and `hermes doctor` (full check of config, deps, and gateway health). `hermes doctor` also detects the install method (git, Docker, NixOS) and shows the matching update command.