Running Hermes Agent on an Ubuntu Server

An agent that only runs while your laptop is open is a demo. Put it on a small server, give it a stable home and a narrow front door, and it starts to behave like infrastructure. This guide sets up Hermes Agent, the open-source agent from Nous Research, on Ubuntu Server 24.04, with Telegram as the way you talk to it.

The commands come from the project's own documentation. Hermes moves quickly, so check the official docs before you copy anything into a production machine.

What you need

• A server running Ubuntu Server 24.04. The gateway itself is light, because the model runs at your provider, so a small VPS is enough to start.
• SSH access with a key, and an account that can use sudo.
• An API key for a model provider. Hermes supports Nous Portal, OpenRouter, OpenAI and any compatible endpoint.
• A Telegram account, if you want to reach the agent from your phone.

1. Give the agent its own account

Hermes can run shell commands for you. That is the point, and it is also the risk. A dedicated, unprivileged user limits what a bad instruction or a confused model can touch.

sudo adduser --disabled-password --gecos "" hermes
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git

Do not add this user to the sudo group. If the agent ever needs elevated access for a task, that is a decision you make, not one it makes.

Keep the firewall closed by default and open only what you use:

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status verbose

2. Install Hermes

Switch to the new user and run the official installer. Reading a script before piping it into a shell is a good habit, so download it first:

sudo -iu hermes
curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o install.sh
less install.sh
bash install.sh
source ~/.bashrc

Everything Hermes keeps lives under ~/.hermes in this user's home directory: configuration, memory and the skills it learns over time. That folder is what you back up later.

3. Configure a model and run it once

The setup wizard walks through providers, models and tools:

hermes setup

You can change individual pieces afterwards without repeating the whole wizard:

Before connecting anything else, start an interactive session with hermes and ask it something simple. If that fails, hermes doctor is the fastest way to find out why. Fixing a model problem is much easier here than through a chat app.

4. Connect Telegram, and decide who may talk to it

Create a bot with @BotFather and keep the token somewhere private. Then run the gateway wizard:

hermes gateway setup

The gateway denies everyone by default unless they are on an allowlist or paired through a direct message. Keep it that way. There are two ways to let yourself in:

1. Pairing. Message the bot. Unknown users receive a short code, which you approve on the server. Codes expire after an hour.
2. An allowlist. Set TELEGRAM_ALLOWED_USERS to your numeric Telegram user ID (a comma-separated list for several people) in the gateway's environment. The configuration guide in the docs shows where your install keeps it.

hermes pairing approve telegram <CODE>
hermes pairing list
hermes pairing revoke telegram <USER_ID>

There is also a GATEWAY_ALLOW_ALL_USERS=true switch. The documentation marks it as not recommended for bots with terminal access, and that is an understatement: on a server like this one it means anyone who finds the bot can run commands as the hermes user.

5. Keep the gateway running

hermes gateway runs in the foreground, which is perfect for a first test. For an always-on agent, install it as a service. On Linux, hermes gateway install creates a systemd user service, and user services stop when that user logs out. Turn on lingering from your admin account so it keeps running:

sudo loginctl enable-linger hermes

Back in the hermes account, point the shell at the user's systemd instance. A shell opened with sudo -iu does not set this for you, and systemctl --user fails without it:

export XDG_RUNTIME_DIR="/run/user/$(id -u)"
hermes gateway install
hermes gateway start
hermes gateway status

Logs go to the journal:

journalctl --user -u hermes-gateway -f

If you prefer a boot-time system service instead, the documentation also describes hermes gateway install --system.

6. Updates, restarts and backups

hermes update
hermes gateway restart
hermes doctor

hermes gateway restart lets in-flight conversations finish before it restarts, so it is safe to run while someone is mid-request.

Back up ~/.hermes on a schedule and copy it off the machine. Treat the archive as sensitive: it holds credentials and everything the agent remembers.

tar -czf "hermes-$(date +%F).tar.gz" -C "$HOME" .hermes

A short checklist

• The agent runs as its own user, without sudo.
• Only SSH is open to the internet.
• Telegram access is limited to paired or allowlisted users.
• The gateway survives logouts and reboots.
• ~/.hermes is backed up somewhere else, and you have tried restoring it once.

That last item is the one people skip. A backup you have never restored is a hope, not a plan.