How to Install Hermes Agent on Linux
Ubuntu, Debian, Fedora, Arch — one command — plus the headless server and systemd service-user recipe. A platform page of the install guide, cross-checked against the official docs.
TL;DR
One command on any supported distro. Linux (x86_64 and aarch64) is Tier 1; Nous tests on the latest Ubuntu, and the official matrix says "if your distro has glibc, systemd, and follows the Filesystem Hierarchy Standard, it's likely to work pretty well."
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes # start chattingThis guide covers Hermes Agent v0.21.5. On other platforms? See Windows, macOS, Raspberry Pi, or VPS.
Prerequisites
Per the official install docs: Git, plus curl and xz-utils (the installer downloads Node.js as a .tar.xz) — on Debian/Ubuntu that's sudo apt install git curl xz-utils. The desktop app additionally needs build-essential to compile native modules. Everything else the installer handles itself, with no sudo: uv, Python 3.11, Node.js 26 (existing Node 22.22+/24.11+/26+ is used as-is), ripgrep, and ffmpeg.
Install layout: per-user vs system-wide
| Installer | Code lives at | hermes binary | Data directory |
|---|---|---|---|
| Per-user (default) | ~/.hermes/hermes-agent/ | ~/.local/bin/hermes (symlink) | ~/.hermes/ |
Root mode (curl … | sudo bash) | /usr/local/lib/hermes-agent/ | /usr/local/bin/hermes | /root/.hermes/ or $HERMES_HOME |
The root-mode FHS layout is for shared machines where one system install serves every user — per-user config (auth, skills, sessions) still lives under each user's own ~/.hermes/. For a personal machine, the per-user default is what you want.
Ubuntu Server, headless boxes, and systemd service users
Running Hermes as a dedicated unprivileged user — a hermes systemd service account, or any user without sudo — is officially supported. The only step on the install path that genuinely needs root is Playwright's Chromium system libraries. The recommended split:
- Once, as an admin:
sudo npx playwright install-deps chromium. - As the service user: run the regular installer. It detects the missing sudo and degrades gracefully — Chromium goes into the user's own Playwright cache. Headless and don't need browser automation at all? Add
--skip-browser(and--skip-computer-use):curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser - PATH: service accounts often lack
~/.local/binon PATH — add it to the user's profile, or symlink the venv launcher into/usr/local/bin. - Verify:
hermes doctorshould run cleanly. (AModuleNotFoundError: dotenvmeans you're invoking the repo source file with system Python instead of the venv launcher — fix step 3.) - Gateway at boot: a user-level service stops at logout until you enable lingering —
sudo loginctl enable-linger <service-user>.hermes gateway setupoffers to install the systemd user unit itself.
Doing this on a rented server? The VPS page adds sizing, the Docker alternative, and the security guidance for exposing anything publicly.
Distro notes
- Ubuntu / Debian — the tested reference platform. Fresh minimal cloud image:
apt-get install -y git curl xz-utilsfirst. - Fedora / RHEL / openSUSE — same installer; these distros don't support Playwright's
--with-deps, so an admin installs the Chromium system libraries separately — the installer prints the exactdnf/zyppercommands. - Arch / Manjaro — the installer works (pacman, same sudo-detection). The AUR package is explicitly unsupported — use the official installer.
- Nix / NixOS — no longer an explicitly supported path (Tier 2, best-effort; "breaks often due to node.js packaging woes" per the official matrix). The Nix setup guide has a flake and NixOS module if you accept the tradeoff.
- Alpine — musl, not glibc: outside the "likely to work" description. A Debian container or VPS is the path of least resistance.
Updating
Hermes auto-detects how it was installed, and hermes update updates a git-installer layout in place (Docker installs update by pulling a new image instead — hermes update is intentionally unsupported there). hermes doctor shows the detected install method.
FAQ
How do I install Hermes Agent on Ubuntu?
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash, then source ~/.bashrc. Ubuntu is the distro Nous tests against; on a fresh minimal image, install git curl xz-utils first.
Does the installer need sudo?
No for the core install — it's per-user under ~/.hermes/. Root is only needed once for Playwright's Chromium system libraries, and --skip-browser avoids even that.
Which distros are supported?
Latest Ubuntu and WSL2 are tested; anything with glibc, systemd, and FHS is expected to work — Debian, Fedora, Arch, openSUSE. Alpine (musl) doesn't fit that description.
Can I install from the AUR on Arch?
No — AUR installs are explicitly unsupported. Run the official installer on Arch instead.
How do I keep the gateway running on a server?
Install as a service user, run hermes gateway setup (systemd user unit), and sudo loginctl enable-linger <user> so it starts at boot and survives logout.
What about NixOS?
Tier 2 / best-effort — the official guide is extensive, but releases may break it. Docker or an FHS distro is the supported path.
Next: verify the install, pick a model provider, then the Skills Hub. Running on ARM or a rented box? Raspberry Pi and VPS build on this page.