HermesAgentAIIndependent Guide
Install
Installation guide

Install Hermes Agent

Two official ways in: download the Hermes Desktop app (macOS on Apple Silicon, Windows), which also installs the command line — or run the one-line installer for a terminal-only install on macOS, Linux, WSL2, or native Windows. Both are free and come from Nous Research.

Checked against the official installation and platform-support docs on September 26, 2026 (latest release v0.21.5).

Before you start

Supported platforms

macOS on Apple Silicon, Windows 10/11 (x86_64 or ARM64), Linux and WSL2 (x86_64 or ARM64), Docker. Intel Macs are not supported by the macOS installer.

Python

Nothing to install yourself. The installer provides a pinned Python 3.14 plus Node.js, ripgrep, and FFmpeg.

Tools needed first

Linux/macOS: git, curl, tar, and SHA-256 utilities. Windows fetches a pinned Git for Windows if Git is missing.

Browser tools

Installed by default (agent-browser with a pinned Chromium). Skip with --skip-browser (POSIX) or -SkipBrowser (Windows).

Option A: Hermes Desktop (macOS, Windows)

Get the installer from the official Hermes Desktop page. It sets up the desktop app and the hermes command together. Already have the CLI? Run hermes desktop to build and open the app with your existing config. Linux has no packaged Desktop release; hermes desktop builds it locally.

Sources disagree: On September 26, 2026 the Desktop download buttons link to Hermes-Setup.dmg and Hermes-Setup.exe. The installation docs describe Hermes-Setup as a bootstrap installer that downloads and builds a source install, and separately document self-contained bundles: a macOS DMG (drag Hermes.app to Applications) and a Windows .appinstaller MSIX package that requires Windows 11 22H2 or later, plus a Microsoft Store variant. Either route ends with a working install; the bundles skip the first-launch build.

What the app does once installed: Hermes Desktop guide.

1

Option B: run the one-line installer

The script clones Hermes, prepares its pinned runtime, creates the hermes launcher (~/.local/bin on Linux/macOS, %LOCALAPPDATA%\hermes\bin on Windows), and — when run interactively — starts the setup wizard. Data lives in ~/.hermes (%LOCALAPPDATA%\hermes on native Windows).

Command-line install for macOS (Apple Silicon), Linux, and WSL2. Android uses the Termux package instead (pkg install hermes-agent, best effort).

Linux / macOS / WSL Terminal
bash
$curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
Installs to ~/.hermes with a pinned, managed Python runtimeNext: reload shell (`source ~/.bashrc` or `source ~/.zshrc`)

Native Windows or WSL2?

  • Native Windows 10/11 is a Tier 1 platform in the official support matrix — the same priority as macOS and Linux. Several older guides still call it an early beta; the current official docs do not.
  • The PowerShell installer needs no admin rights and adds hermes to your user PATH. Open a new terminal afterwards.
  • hermes gateway install on Windows uses a Scheduled Task, so messaging runs while you are logged in.
  • WSL2 installs coexist with native ones (WSL data lives in ~/.hermes). The web dashboard's in-browser Chat tab needs WSL2; its other pages work natively.

Docker and Android

  • Docker (Tier 1, amd64 and arm64): use the Docker tab above. Your state lives in the mounted ~/.hermes directory. Update by pulling a new image — hermes update does not apply to Docker. Storage, ports, and pitfalls: Hermes in Docker.
  • Android / Termux (Tier 2, aarch64 only): the supported path is a signed APT repository followed by pkg install hermes-agent, not the install script. As of September 26, 2026, the official Termux page says the package is currently broken and a fix is in progress.
2

Reload your shell

Bash (most Linux / WSL):
$source ~/.bashrc
Zsh (macOS default):
$source ~/.zshrc
3

Verify the install

Verify
bash
$hermes --version   # prints the installed version
$hermes doctor      # checks dependencies and reports how Hermes was installed
Installed. If hermes --version prints a version, the CLI works. Connecting a model and your first chat happen in setup.

Update or uninstall

Script installs
bash
$hermes update               # script (git) installs
$hermes update --check       # preview only
$hermes uninstall --dry-run  # see what would be removed
$hermes uninstall            # remove Hermes, keep config and chats
$hermes uninstall --full     # also remove all user data

Desktop bundles update from inside the app (Settings → About); Docker updates by pulling a new image. Don't delete ~/.hermes to “repair” an install — it holds your config, memory, and sessions.

Install problems and fixes

`hermes: command not found` after install

Cause: Your current shell has not loaded the launcher directory (~/.local/bin on Linux/macOS) into PATH.

Fix: Run `source ~/.bashrc` or `source ~/.zshrc`, or open a new terminal. On Windows, open a new PowerShell window.

Installed with pip, uv tool, Homebrew, or the AUR

Cause: The official platform-support page lists these install methods as unsupported.

Fix: Reinstall with the official installer or Desktop package. `hermes doctor` reports how the running copy was installed.

PowerShell installer blocked by policy

Cause: Execution policy or endpoint protection may block a remotely downloaded script.

Fix: Use the Desktop installer, or follow your administrator's approved process for running the PowerShell installer.

Building Desktop from source fails on Linux

Cause: Source builds can need a native compiler and development libraries; Linux has no packaged Desktop release.

Fix: Install your distribution's build tools (on Debian/Ubuntu, `sudo apt-get install -y build-essential`) and rerun `hermes desktop`.

Corporate proxy or TLS inspection breaks the download

Cause: curl or PowerShell cannot verify certificates through an inspecting proxy.

Fix: Point curl at your organization's CA bundle (`CURL_CA_BUNDLE`) and proxy, e.g. `curl -fsSL --proxy http://proxy:port https://hermes-agent.nousresearch.com/install.sh | bash`.

Sources: Installation, Platform Support, Windows (Native), Termux, Updating & Uninstalling (official docs).

Next step

Set up Hermes Agent

Connect a model — Nous Portal, a subscription, an API key, or a local model — and verify your first chat.

Continue to setup