Install Hermes Agent on Ubuntu

Before You Start

Ubuntu 22.04 LTS and 24.04 LTS are both fine. You need:

• A user with sudo (the agent itself does not run as root)
• curl installed — sudo apt install -y curl
• Outbound HTTPS to your model provider
• 2 GB RAM comfortably, 1 GB as an absolute floor — see system requirements

Do Not Install Python First

This is the single most common way people make an Ubuntu install harder than it needs to be. The Hermes installer bundles Python 3.11, along with Node, ripgrep and ffmpeg. Installing a system Python and then trying to pip install into it produces a version mismatch that surfaces much later as a confusing tool failure.

Ubuntu 24.04 ships Python 3.12 and marks the system environment as externally managed, so a manual pip install fails anyway. Let the installer own its runtime.

If you deliberately install via pip instead of the script, run hermes postinstall afterwards — that is the command that bootstraps the non-Python dependencies (Node, the browser, ripgrep, ffmpeg) the pip package does not carry.

Install

sudo apt update && sudo apt install -y curl
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Open a new shell afterwards (or source ~/.bashrc) so hermes is on your PATH, then confirm:

hermes --version
hermes doctor

hermes doctor checks configuration and dependencies. Run it now, while the install is untouched — it is far easier to interpret a clean failure than one buried under later config changes.

Configure a Model and Channels

hermes setup

The wizard walks through provider auth, model choice, and messaging platforms in one pass. If you would rather do it piecemeal, hermes model selects the model and hermes gateway setup configures platforms.

Run It as a Service

A foreground hermes process dies when your SSH session ends. On Ubuntu, register the systemd service instead:

hermes gateway install
hermes gateway status

This installs hermes-gateway.service as a user unit. Full lifecycle commands are in the background service guide.

One Ubuntu-specific detail: user services stop when the user logs out unless lingering is enabled. If your agent dies after you disconnect, this is why:

sudo loginctl enable-linger $USER

Firewall

Ubuntu ships ufw. Hermes needs outbound HTTPS, which is allowed by default. You only need inbound rules if you expose the web UI or accept channel webhooks:

sudo ufw allow OpenSSH
# Only if you terminate TLS here for webhooks:
sudo ufw allow 80,443/tcp
sudo ufw enable

Do not open the backend server port (9119 by default) to the internet. It binds 127.0.0.1 for a reason — put a reverse proxy or a Tailscale tunnel in front instead.

Keeping It Updated

hermes update
hermes gateway restart

If hermes update warns about legacy service units, act on it — a stale hermes.service alongside the current hermes-gateway.service makes the two fight over the same bot token. Fix it with hermes gateway migrate-legacy.

Common Ubuntu Issues

“command not found: hermes”

The PATH change has not reached your shell. Open a new session or source ~/.bashrc.

Agent stops when you close SSH

Either you are running in the foreground, or you installed the service without lingering enabled. Install the service and run sudo loginctl enable-linger $USER.

Externally-managed-environment pip error

You are trying to pip install into Ubuntu's system Python. Use the install script instead, which manages its own runtime.

Out-of-memory kills on a 1 GB box

The browser tooling is the usual trigger. Add swap as a stopgap, but 2 GB is the honest number once browsing is enabled.

Skip the Server Entirely

OpenClaw Launch runs Hermes Agent as a managed container — no systemd, no lingering, no firewall rules. If you prefer self-hosting, compare providers in the best Hermes hosting guide or see the Hermes VPS guide.