Applied Hermes
Set up Hermes Agent

Software acquisition Independent guide

Install Hermes Agent

Choose an installation method, install Hermes Agent, and verify the runtime. Provider setup and first use happen after this.

Published by Applied Hermes. Checked against Hermes Agent v0.20.5 on .
Direct answer

There are five supported ways to get Hermes Agent. The four Tier 1 (fully supported) methods are: the desktop installer (macOS and Windows), the shell installer on macOS, Linux, and WSL2, the PowerShell installer on native Windows, and the published container image. The one Tier 2 (best-effort) method is the Nix/NixOS install. Choose by platform and by whether you want a graphical app, a host install, or an isolated container — then verify the runtime before configuring anything.

Checked against Hermes Agent v0.20.5 on . Re-check when an installer URL, a supported platform, an install path, or the verification command changes in a release.

Choose the right Hermes Agent installation method

Every method below is listed in full so the choice is readable without JavaScript. Pick one; you can change later, because all methods share the same data directory.

  1. Desktop installer

    Choose this when: you are on macOS or Windows and want a graphical application that manages the backend for you.

    Prerequisite: A supported desktop OS. On Linux, desktop support also needs build tooling installed.

    Downloaded from the Nous Research product page. Setup, connection, and removal are covered in the desktop installation guide.

  2. Shell installer

    Choose this when: you are on macOS, Linux, WSL2, or Termux and want the CLI on the host.

    Prerequisite: Git on PATH. On Linux also curl and xz-utils.

    One command; the universal procedure below.

  3. PowerShell installer

    Choose this when: you are on native Windows 10 or 11 and are not using WSL2.

    Prerequisite: PowerShell or Windows Terminal. Administrator rights are not required.

    Windows has its own paths, PATH behaviour, and one documented feature limitation. See Windows installation.

  4. Container image

    Choose this when: you want the runtime isolated, reproducible, or running on a server.

    Prerequisite: A working Docker installation and a host directory for persistent state.

    Updates work differently in a container. See Docker deployment.

  5. Nix / NixOS (Tier 2 — best effort)

    Choose this when: you already use Nix or NixOS and want a declarative, reproducible install (flake, NixOS module, or Home Manager module).

    Prerequisite: Nix with flakes enabled. The install.sh method also works but is maintained in-tree only as a best effort; expect it to break more often than Tier 1 methods.

    Nix setup commands and module options are owned by the official Nix & NixOS setup guide. Tier 2 means the official docs promise best-effort maintenance, not Tier 1 stability.

Source: Nous Research Installation and Platform Support documentation, checked 25 August 2026 against v0.20.5.

Universal prerequisites

  • Git available on PATH. Check with git --version. On native Windows the installer provisions a portable Git if none is found.
  • On Linux: curl and xz-utils. Desktop-app support additionally needs build tooling.
  • Everything else is provisioned for you. The installer handles Python 3.11, Node.js, ripgrep, and ffmpeg. The Node.js version differs by platform and release — the general installation guide documents v22, while the Windows guide and the container image document Node.js 26 — so do not treat a single Node version as universal.
  • A model provider is not a prerequisite for installing, only for using. Installation and provider setup are separate steps on purpose.

Desktop, native installer, source, or Docker?

Installation methods comparedWhere code lands = the directory the installer writes program files to. Update path = the supported way to move to a newer release. Isolation = what separates the agent from the rest of the machine by default.
MethodWhere code landsUpdate pathIsolation
Desktop installerManaged by the app inside the Hermes home directoryIn-app update promptNone beyond normal OS boundaries
Shell installer~/.hermes/hermes-agent/ with a symlink at ~/.local/bin/hermeshermes updateNone beyond normal OS boundaries
PowerShell installer%LOCALAPPDATA%\hermes\hermes-agent\hermes updateNone beyond normal OS boundaries
Container imageInside the image; state on a mounted volumePull a new image and recreate the containerContainer boundary
Nix / NixOS (Tier 2)Flake-derived; system or home package via `nix run` or `nix profile install`Re-pull input or rebuild the flakeContainer or OS boundary, depending on module

Source: Nous Research Installation, Windows Native, Updating, Docker, and Platform Support documentation, checked 25 August 2026.

Root-mode shell installs place code in /usr/local/lib/hermes-agent/, the binary in /usr/local/bin/hermes, and data in /root/.hermes/ or $HERMES_HOME. Prefer the per-user install unless a shared-server requirement forces otherwise.

Universal installation procedure

bashmacOS, Linux, WSL2, Termux (Tier 1 + Tier 2)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Expected result: The installer provisions dependencies, clones the code, creates a virtual environment, sets up the global `hermes` command, and offers provider configuration.

This pipes a remote script into a shell. If your environment requires review before execution, download the script, read it, then run it.

Source: Nous Research Installation guide, checked 25 August 2026

Then reload the shell so the new PATH entry is picked up:

bashmacOS, Linux, WSL2, Termux (Tier 1 + Tier 2)
source ~/.bashrc

Expected result: No output. A new terminal window achieves the same thing.

Source: Nous Research Installation guide, checked 25 August 2026

Use source ~/.zshrc instead if zsh is your shell.

Windows-specific path

Native Windows uses its own installer, its own install root under %LOCALAPPDATA%\hermes\, and its own PATH behaviour, and it has one documented feature that is unavailable natively.

PowerShellWindows 10 and 11
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Expected result: Dependencies, code, and the `hermes` command are installed under %LOCALAPPDATA%\hermes\, and the setup wizard runs.

Open a new PowerShell window afterwards; existing terminals do not pick up the PATH change.

Source: Nous Research Installation guide, checked 25 August 2026

Prerequisites, the native-versus-WSL2 decision, security prompts, and Windows-only failures are owned by Windows installation.

Docker-specific path

The container path pulls a published image and keeps all state on a mounted host directory.

bashAny Docker host
docker pull nousresearch/hermes-agent:latest

Expected result: The image is downloaded locally and is ready to run.

Source: Nous Research Docker guide, checked 25 August 2026

Do not start there without reading the persistence and exposure steps. hermes update is explicitly not supported for container installs — you update by running a new image. Full setup is owned by Docker deployment.

macOS and Linux paths

Both use the shell installer above; the differences are environmental.

  • macOS is supported on Apple Silicon. Intel Macs are listed as unsupported.
  • Linux is tested on Ubuntu and WSL2, and expects glibc, systemd, and a standard filesystem layout. WSL2 is documented as performing equivalently to native Linux.
  • Termux on Android is best-effort support with known restrictions.
  • Nix / NixOS is Tier 2 (best effort) and is documented on the Nix & NixOS setup page. Use the shell installer from inside a Nix shell, the Nix flake, the NixOS module, or the Home Manager module depending on your setup.

Nix / NixOS path (Tier 2)

Verify runtime installation

Run both checks before touching configuration:

bashmacOS, Linux, WSL2, Windows PowerShell
hermes --version

Expected result: A version string is printed. If the command is not found, the shell has not reloaded PATH — open a new terminal.

Source: Nous Research FAQ and Windows Native guide, checked 25 August 2026

bashmacOS, Linux, WSL2, Windows PowerShell
hermes doctor

Expected result: A diagnostic report covering configuration, dependencies, provider authentication, and backend availability.

Source: Nous Research Installation guide, checked 25 August 2026

A successful install means the command resolves and hermes doctor runs. It does not mean the agent can do anything useful yet.

What installation does not configure

Installing gets you a runtime. It does not decide:

  • Which model provider you use, or where your credentials live.
  • Which toolsets are enabled, or which terminal backend runs commands.
  • What the agent is allowed to do without asking, which is the approval-mode decision.
  • Whether anything is exposed on the network, which stays off until you turn it on.

Those are separate, owned decisions — and skipping them is how an install becomes an incident.

Route platform/install failures

If the installer fails, the command is missing, or a dependency will not resolve, do not reinstall repeatedly. Capture the exact error text first, then work through installation troubleshooting, which isolates the failing layer before changing anything.

Continue to first result

Installation is step one of five. Provider connection, safe defaults, a bounded first task, and verification are owned by getting started after installation.

Continue to your first verified result