Guides

How to install Hermes Agent on Linux

Published August 5, 2026 · Verified on v0.19.0

Linux is where Hermes is most at home, and where most people end up running it long-term — a small always-on box is the natural host for an agent that is supposed to answer at 4am.

Step 1 — prerequisites

The installer handles language runtimes itself, but it needs a few basics present first.

Debian, Ubuntu, and derivatives:

sudo apt update && sudo apt install -y git curl xz-utils

Fedora / RHEL:

sudo dnf install -y git curl xz

Arch:

sudo pacman -S --needed git curl xz

If you also plan to run the desktop GUI, add a compiler — build-essential on Debian-family systems, gcc-c++ on Fedora.

Step 2 — create a normal user if you are on a fresh server

Skip this on your own desktop. On a VPS where you are still logged in as root, make a user first:

adduser hermes
usermod -aG sudo hermes
su - hermes

This matters more than it looks. Hermes installs into the home directory of whoever runs the installer, so installing as root leaves you with an agent under /root that your everyday user cannot reach.

Step 3 — install

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

No sudo. If you want to read the script before running it — a reasonable habit for anything piped into a shell:

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

The run takes roughly a minute and pulls uv, Python 3.11, Node.js v22, ripgrep and ffmpeg. Code lands in ~/.hermes/hermes-agent/, and the launcher is symlinked to ~/.local/bin/hermes.

Step 4 — reload your shell

source ~/.bashrc

If hermes is still not found after this, ~/.local/bin is not on your PATH — the fix takes one line.

Step 5 — verify before configuring

hermes doctor

Run this before touching model settings or gateways. It checks dependencies, config paths and provider setup together, and it is the difference between a specific answer and an evening of guessing.

Step 6 — pick a model and talk to it

hermes model     # choose your provider
hermes           # start chatting

If the first message dies with an HTTP 400, the model identifier does not match what your provider publishes — diagnose it in one command.

Keeping it running after you log out

This is the step most guides skip, and it is the one that matters on a server. A gateway started in an SSH session dies with the session.

Create ~/.config/systemd/user/hermes.service:

[Unit]
Description=Hermes Agent gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=%h/.local/bin/hermes gateway
Restart=on-failure
RestartSec=10
Environment="PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin"

[Install]
WantedBy=default.target

The explicit Environment=PATH line is not optional. systemd starts with a minimal environment that does not include your shell profile, so without it the unit fails with the same “command not found” that works fine in your terminal.

Enable it, and enable lingering so it survives logout and reboot:

loginctl enable-linger "$USER"
systemctl --user daemon-reload
systemctl --user enable --now hermes
systemctl --user status hermes

Once the gateway survives logout, follow the Hermes Agent Telegram setup to create a private bot, restrict it to your numeric user ID and test message delivery.

Firewall

Hermes with chat gateways makes outbound connections. It does not need inbound ports open beyond SSH:

sudo ufw allow OpenSSH
sudo ufw enable

An agent with filesystem and shell access is not something to leave reachable from the open internet.

Upgrading later

Snapshot the machine first — Hermes ships releases most weeks and not all of them are quiet. Check the changelog for breaking changes before you pull, and re-run hermes doctor afterwards.

FAQ

Which distributions are supported?

Anything current with glibc — Ubuntu, Debian, Fedora, Arch and their derivatives all work. The installer brings its own Python and Node.js rather than depending on your distro's packages, so distro version matters far less than usual.

Should I install with sudo?

No. A root install puts Hermes and its persistent memory under /root, where your normal user cannot read them. If you already did it, remove the root-owned install before reinstalling as yourself.

Why does the agent stop when I close my SSH session?

Because a process started in a terminal dies with that terminal. Run the gateway under a systemd user unit with lingering enabled, which is covered below.

Do I need to install Python 3.11 first?

No. The installer pulls uv, Python 3.11, Node.js v22, ripgrep and ffmpeg itself. Installing them yourself first is unnecessary and occasionally causes version conflicts.