How to Install Hermes Agent on Ubuntu 26.04 and Keep It Running

TL;DR:

• Run the official installer as your sudo user, connect a model with hermes setup model and Telegram with hermes gateway setup, then install the gateway as a systemd system service that starts at boot.
• Checked with Hermes Agent v0.22.5 on Ubuntu 26.04 and 24.04. Use v0.22.2 or later, which fixed a supervised gateway that could refuse to start after a reboot.
• The official Docker guide sets 1 core and 1 GB RAM as the minimum and 2 cores with 2 to 4 GB as recommended. Without browser tools, the installer ran for 1 to 6 minutes and used about 2.2 GB of disk.
• sudo hermes returns command not found because sudo resets PATH. Use sudo HERMES_HOME="$HOME/.hermes" "$HOME/.local/bin/hermes" gateway install --system --start-now --start-on-login.
• UFW allows only OpenSSH (22/tcp). The optional API server (8642) and the dashboard (9119) bind to 127.0.0.1.
• In Docker, pin nousresearch/hermes-agent:v0.22.5 and publish ports on 127.0.0.1 only.

Applies to: Ubuntu 26.04 LTS and 24.04 LTS · Hermes Agent v0.22.5 · checked October 2026

Hermes Agent is an open-source AI agent from Nous Research, released under the MIT License, that keeps memory and skills between sessions, runs scheduled jobs, and replies in Telegram, Discord, Slack and other chat apps through one gateway process. This tutorial installs Hermes Agent on Ubuntu 26.04, connects a model provider and a Telegram bot, and runs the gateway as a systemd service that starts at boot, then covers Docker, a local Ollama model, updates, backups and removal. A server keeps the gateway online while your laptop sleeps.

How much RAM does Hermes Agent need?

The official Docker guide gives these resource figures for Hermes Agent:

With browser tools active, the guide asks for at least 2 GB of RAM.

On Arct Cloud, the Cost Optimized cvm.pico plan (1 vCPU, 1 GB RAM, 15 GB NVMe) meets the minimum without browser tools, and cvm.micro or General Purpose vm.micro (2 vCPU, 4 GB RAM, 40 GB NVMe each) match the recommended profile. The Hermes Agent plan page lists the Cost Optimized sizes. An API model runs inference off the server; a local Ollama model at the 64,000-token context Hermes needs takes more than 3 GB of RAM on top.

Prerequisites

• A server running Ubuntu 26.04 LTS with SSH access and the resources above. The installer, the system service in Step 5 and hermes update also ran on Ubuntu 24.04 LTS.
• A non-root user with sudo privileges and SSH key login. How to Generate an SSH Key on Windows, macOS, and Linux covers creating the key and giving a sudo user access.
• An API key from a model provider such as OpenRouter, Anthropic or OpenAI, or a Nous Portal account.
• A Telegram account to create a bot with @BotFather.

Commands run as the sudo user, shown as deploy in sample output. Replace values written in capitals, such as YOUR_SERVER_IP, with your own.

Step 1: Update the server and allow only SSH in UFW

The installer needs Git and curl, plus tar and sha256sum, which Ubuntu includes. The Node.js build that Hermes downloads also links libatomic.so.1, which minimal Ubuntu images do not ship, and the non-interactive install in Step 2 never asks for a sudo password to add it. Install curl, Git and libatomic1 first:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git libatomic1

Allow SSH before you enable the Uncomplicated Firewall (UFW), or the current session drops:

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status verbose

Type y to confirm. The output looks similar to this:

Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), disabled (routed)
New profiles: skip

To                         Action      From
--                         ------      ----
22/tcp (OpenSSH)           ALLOW IN    Anywhere
22/tcp (OpenSSH (v6))      ALLOW IN    Anywhere (v6)

Telegram and Discord need no inbound port. Port 8642 serves only the optional API server in Step 6.

Step 2: Run the official Hermes Agent installer

Run the installer from hermes-agent.nousresearch.com as your sudo user, without sudo. Run as root, it installs into root's home directory:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --non-interactive --skip-browser --skip-computer-use

• --non-interactive skips the setup and gateway stages. An interactive run ends by installing a user service; Step 5 installs a system service instead.
• --skip-browser leaves out the browser tools (agent-browser and Chromium). Add them later with hermes pm install agent-browser on a server with 2 GB of RAM or more; Chromium also needs Ubuntu system libraries that the installer does not add.
• --skip-computer-use leaves out the computer-use driver. hermes update keeps both choices.

The script clones the latest stable release into ~/.hermes/hermes-agent, downloads pinned Python 3.14 and Node.js builds, and adds ~/.local/bin to PATH in ~/.bashrc. The output ends like this:

✓ Install complete! [detached @ bf0203a794]
...
✓ added ~/.local/bin to PATH in /home/deploy/.bashrc
✓ app products and hermes command ready
✓ Hermes Agent install complete. Run: hermes
→ Reload your shell to use hermes: open a new terminal, or run: source ~/.bashrc

Reload the shell and check the version:

source ~/.bashrc
hermes --version

Hermes Agent v0.22.5 (2026.9.24) · stable · local bf0203a794a0
Install directory: /home/deploy/.hermes/hermes-agent
Install method: git
Python: 3.14.9
OpenAI SDK: 2.24.0
Up to date

At the time of testing, the installer installed Hermes Agent v0.22.5, ran for 1 to 6 minutes, and left about 2.2 GB in ~/.hermes, mostly the code checkout and its bundled Python and Node.js. Your output may show a newer version. hermes doctor checks Python, the config files, providers and tools, and on a fresh install it flags the provider and chat platforms that Steps 3 and 4 set up.

Step 3: Connect a model provider with hermes setup

hermes setup model runs only the provider section of the setup wizard. hermes model changes the provider or model later:

hermes setup model

Pick a provider with the arrow keys and Enter. Nous Portal signs in through a device-code link that you open in a local browser. OpenRouter, Anthropic, OpenAI and most other entries ask for an API key. For OpenRouter, the prompt looks like this:

Get one at: https://openrouter.ai/keys

No OpenRouter API key configured.
OPENROUTER_API_KEY (or Enter to cancel):

Paste the key and pick a default model from the list. For a model with reasoning settings, the wizard then asks for a reasoning effort; press Enter to keep medium. The wizard ends with:

✓ Model & Provider configuration complete!

Hermes stores the key in ~/.hermes/.env, which only your user can read (mode 600), and the model in ~/.hermes/config.yaml. To sign in to Nous Portal and set it as the provider in one command, run hermes setup --portal instead.

Test the provider before you add Telegram:

hermes chat -q "Reply with the single word ready." --oneshot -Q

A one-word reply confirms the key and the model. If the command prints an API key error, run hermes setup model again.

Step 4: Connect Telegram with hermes gateway setup

In Telegram, message @BotFather, send /newbot, and copy the bot token it returns. Then message @userinfobot to get your numeric Telegram user ID. Start the gateway wizard:

hermes gateway setup

Select Telegram, type 2 for Manual, and paste the token. Automatic pairs a bot through a QR code instead. The wizard then asks who may use the bot:

Allowed user IDs (comma-separated, leave empty for open access):

Enter your numeric ID. With an empty list, the gateway denies everyone, whatever the prompt says, and answers unknown users with a one-time pairing code that you approve with hermes pairing approve telegram YOUR_PAIRING_CODE. Answer Y to use the same ID as the home channel, where Hermes delivers cron job results, then select Done. Discord, Slack, WhatsApp and Signal appear in the same list.

Answer n to both start questions, because Step 5 installs the service. A Y to either one installs a user service:

  Start the gateway now? [Y/n]: n
  Start the gateway automatically on login/boot as a systemd service? [Y/n]: n
    Skipped start and auto-start setup.
    You can install later: hermes gateway install
    Or as a boot-time service: sudo hermes gateway install --system
    Or run in foreground:  hermes gateway run

Once the gateway runs, Hermes asks in the chat before it runs a shell command that its risk check cannot clear. Reply yes to run it or no to block it; with no reply within 300 seconds, the command is denied. Commands run as your user, and the Hermes security guide recommends a container terminal backend for a production gateway.

Step 5: Install the gateway as a system service

Hermes's messaging docs recommend the system service on a VPS or headless host that should come back at boot without relying on systemd linger. The sudo hermes gateway install --system line that the wizard prints fails with sudo: 'hermes': command not found on Ubuntu 26.04 and sudo: hermes: command not found on 24.04, because sudo resets PATH and HOME. With the full path but no HERMES_HOME, Hermes looks for its data under /root. Pass both:

sudo HERMES_HOME="$HOME/.hermes" "$HOME/.local/bin/hermes" gateway install --system --start-now --start-on-login

Your shell expands $HOME before sudo runs, and Hermes reads SUDO_USER to set the service user. --start-now and --start-on-login answer the two start questions, so the unit starts now and at every boot. The output looks similar to this:

Installing system systemd service to: /etc/systemd/system/hermes-gateway.service
Created symlink '/etc/systemd/system/multi-user.target.wants/hermes-gateway.service' → '/etc/systemd/system/hermes-gateway.service'.

✓ System service installed and enabled!
...
Configured to run as: deploy
Enabling linger for deploy so cron and Kanban workers can reach systemd-run --user...
✓ Enabled linger for deploy
...
✓ System service started

The unit runs hermes gateway run as your user with Restart=always. Linger is enabled only so cron workers can start their own systemd scopes. Check the service:

hermes gateway status --system

● hermes-gateway.service - Hermes Agent Gateway - Messaging Platform Integration
     Loaded: loaded (/etc/systemd/system/hermes-gateway.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-10-29 14:59:56 UTC; 22s ago
...
✓ System gateway service is running
Configured to run as: deploy
✓ System service starts at boot without requiring systemd linger

The linger line appears even for a disabled unit, so confirm that the unit starts at boot:

systemctl is-enabled hermes-gateway

enabled

Hermes also documents a user service with linger (hermes gateway install plus sudo loginctl enable-linger $USER), which hermes update can restart without root. Install one or the other, never both, and remove a user unit from an interactive install with hermes gateway uninstall.

Step 6: Keep port 8642 and the dashboard on 127.0.0.1

The API server is off by default. The only Hermes listener is a random loopback port that the gateway uses internally:

sudo ss -tlnp | grep hermes

LISTEN 0      2048       127.0.0.1:34739      0.0.0.0:*    users:(("hermes",pid=3642,fd=23))

Enable the API server on 127.0.0.1 (optional)

The API server on port 8642 lets OpenAI-compatible clients on the same server, such as Open WebUI, talk to the agent. It stays off until API_SERVER_ENABLED=true, and requests must carry API_SERVER_KEY. Add both to ~/.hermes/.env, restart the service and test it:

printf 'API_SERVER_ENABLED=true\nAPI_SERVER_KEY=%s\n' "$(openssl rand -hex 32)" >> ~/.hermes/.env
sudo HERMES_HOME="$HOME/.hermes" "$HOME/.local/bin/hermes" gateway restart --system
curl -s http://127.0.0.1:8642/health

{"status": "ok", "platform": "hermes-agent", "version": "0.22.5"}

The server binds to 127.0.0.1:8642, and a /v1 request without the key gets HTTP 401. Keep 8642 closed in UFW and leave API_SERVER_HOST unset.

Open the dashboard through an SSH tunnel

The web dashboard manages config, API keys, sessions and skills, and has a chat tab. It binds to 127.0.0.1:9119 by default and needs no login there. From your own computer, open an SSH session that forwards the port:

ssh -L 9119:127.0.0.1:9119 deploy@YOUR_SERVER_IP

Replace deploy with your user. In that session, start the dashboard:

hermes dashboard --no-open

HERMES_DASHBOARD_READY port=9119
  Hermes Web UI → http://127.0.0.1:9119

Open http://127.0.0.1:9119 in your local browser. Ctrl+C stops the dashboard; the gateway keeps running under systemd. Keep the default 127.0.0.1 bind: on --host 0.0.0.0, Hermes requires a password or OAuth provider, and the Hermes docs rate the bundled password login unsuitable for direct internet exposure. How to Open a Private Dashboard with an SSH Tunnel saves the forward in ~/.ssh/config.

Step 7: Verify the gateway after a reboot

Hermes v0.22.2 fixed a supervised gateway (systemd, launchd or Docker) that refused to start after a reboot when another process had reused its recorded process ID. Confirm that hermes --version shows v0.22.2 or later, then reboot:

sudo reboot

Reconnect and check the service and the journal for the current boot:

hermes gateway status --system
sudo journalctl -u hermes-gateway -b --no-pager -n 20

The status shows the service running, as in Step 5:

✓ System gateway service is running
Configured to run as: deploy

Then send your bot a message in Telegram. A reply confirms the service, the model provider and the allowlist together.

Run Hermes Agent with Docker instead

The official image is a Tier 1 platform in the Hermes support matrix. Use it on a server without the native install from Steps 2 to 5, so two gateways never poll the same bot. Install Docker Engine and add your user to the docker group with How to Install Docker and Docker Compose on Ubuntu 24.04 and 26.04. Generate a dashboard password with openssl rand -hex 16 and a session secret with openssl rand -hex 32, then start the gateway:

mkdir -p ~/.hermes
docker run -d --name hermes --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -e HERMES_UID="$(id -u)" -e HERMES_GID="$(id -g)" \
  -p 127.0.0.1:9119:9119 \
  -e HERMES_DASHBOARD=1 \
  -e HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin \
  -e HERMES_DASHBOARD_BASIC_AUTH_PASSWORD="YOUR_DASHBOARD_PASSWORD" \
  -e HERMES_DASHBOARD_BASIC_AUTH_SECRET="YOUR_SESSION_SECRET" \
  nousresearch/hermes-agent:v0.22.5 gateway run

• v0.22.5 pins the tested release (Docker Hub tags carry the v). Never use :latest. For an exact pin, use the digest shown after this list in place of the image name.
• ~/.hermes on the host becomes /opt/data: config, .env, sessions, memories and skills.
• HERMES_UID and HERMES_GID make the container write those files as your user. Without them, the files belong to UID 10000 and your user cannot read .env.
• HERMES_DASHBOARD=1 starts the dashboard on 0.0.0.0 inside the container, where Hermes refuses to start it without the BASIC_AUTH login. The secret keeps you signed in across container restarts. Leave out the -p line and the four dashboard lines to run the gateway alone.
• Docker-published ports bypass UFW rules, so the 127.0.0.1: prefix keeps 9119 off the internet. Open the dashboard through the SSH tunnel from Step 6 and sign in as admin.
• Telegram needs no published port. With browser tools, add --shm-size=1g, because Chromium needs shared memory.

The digest of the v0.22.5 image:

nousresearch/hermes-agent@sha256:9c5561579f3ffdf333401797094ac3a743738d6c25d40f4331c7bf77b694238d

Set up the provider and Telegram inside the container, then restart it:

docker exec -it hermes hermes setup model
docker exec -it hermes hermes gateway setup
docker restart hermes

hermes update does not work in the image. Pull the new tag, remove the container, and start it again with the same options and the new tag:

docker pull nousresearch/hermes-agent:YOUR_NEW_VERSION
docker rm -f hermes
docker run -d --name hermes --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -e HERMES_UID="$(id -u)" -e HERMES_GID="$(id -g)" \
  -p 127.0.0.1:9119:9119 \
  -e HERMES_DASHBOARD=1 \
  -e HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin \
  -e HERMES_DASHBOARD_BASIC_AUTH_PASSWORD="YOUR_DASHBOARD_PASSWORD" \
  -e HERMES_DASHBOARD_BASIC_AUTH_SECRET="YOUR_SESSION_SECRET" \
  nousresearch/hermes-agent:YOUR_NEW_VERSION gateway run

Replace YOUR_NEW_VERSION with a newer tag from the GitHub releases page in Next steps. The data in ~/.hermes stays in place, and the new container migrates the config on start.

Use a local Ollama model on demand

Hermes reaches a local Ollama model through Ollama's OpenAI-compatible endpoint. Install Ollama with How to Install Ollama on Ubuntu 24.04 with Open WebUI (CPU Only). Hermes asks for at least 64,000 tokens of context for tool use, and Ollama gives servers without a GPU 4,096 by default. Raise it with a systemd override. If you followed the Ollama tutorial, change only OLLAMA_CONTEXT_LENGTH to 64000 in its override.conf and run the last two commands:

sudo mkdir -p /etc/systemd/system/ollama.service.d
sudo tee /etc/systemd/system/ollama.service.d/override.conf > /dev/null <<'EOF'
[Service]
Environment="OLLAMA_HOST=127.0.0.1:11434"
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_NO_CLOUD=1"
EOF
sudo systemctl daemon-reload
sudo systemctl restart ollama

OLLAMA_HOST keeps the Ollama API on the loopback address, and OLLAMA_NO_CLOUD turns off Ollama's cloud models. The model's own window must reach 64,000 tokens too: after ollama pull, check the context length line of ollama show YOUR_MODEL. qwen3:0.6b stops at 40,960 tokens, and Hermes rejects it. Point Hermes at Ollama and restart the gateway:

hermes config set model.provider custom
hermes config set model.base_url http://127.0.0.1:11434/v1
hermes config set model.default YOUR_MODEL
hermes config set model.context_length 64000
sudo HERMES_HOME="$HOME/.hermes" "$HOME/.local/bin/hermes" gateway restart --system

Replace YOUR_MODEL with a name from ollama list. Test the connection with a one-shot question:

hermes chat -q "Reply with the single word ready." --oneshot -Q

A larger context needs more RAM. With OLLAMA_CONTEXT_LENGTH=64000, Ollama could not load qwen3.5:0.8b within a 3 GB memory limit in the October 2026 checks, and with the gateway running, a 3.8 GB limit also ended in an out-of-memory kill, so a local model needs a server with more than 4 GB of RAM. Best Ollama Models for CPU Servers by RAM Size lists larger models. A local model loads the CPU for the whole of each reply, and sustained full-CPU load is not permitted on Arct Cloud plans, so use it for occasional chats and keep cron jobs and busy chat groups on an API model.

Update Hermes Agent

hermes update follows the stable channel and moves from one published release to the next. v0.22.1 to v0.22.5 shipped between October 14 and October 23, 2026. Check for a new release:

hermes update --check

→ Update channel: stable
→ Selected release available: stable v0.22.5 (bf0203a794a0)
  Run `hermes update` to install it.

Update as your sudo user, then restart the system service:

hermes update
sudo HERMES_HOME="$HOME/.hermes" "$HOME/.local/bin/hermes" gateway restart --system

Without passwordless sudo, hermes update leaves a system unit running during the code swap and restarts it at the end. With passwordless sudo, it stops the unit for the swap and can leave it stopped. In both cases the unit definition stays outdated until the second command, which needs root, rewrites it and restarts the gateway on the new code:

↻ Updated gateway system service definition to match the current Hermes install
...
✓ System service restarted (PID 4053)

Without that restart, hermes gateway status --system warns Installed gateway service definition is outdated. The config.yaml that the installer writes sets pre_update_backup: false, so hermes update saves no backup of its own. hermes update --backup zips ~/.hermes into ~/.hermes/backups/ first, and hermes import restores that zip if you need to roll back.

Back up ~/.hermes

~/.hermes holds the configuration, the API keys in .env, sign-in tokens in auth.json, the session database, memories and skills. hermes backup zips it without the code checkout and downloaded tools, and it runs while the gateway is up:

mkdir -p ~/hermes-backups
hermes backup -o ~/hermes-backups/
chmod 600 ~/hermes-backups/*.zip

Backup complete: /home/deploy/hermes-backups/hermes-backup-2026-10-29-151146.zip
  Files:       380
  Original:    9.5 MB
  Compressed:  1.8 MB
...
Restore with: hermes import hermes-backup-2026-10-29-151146.zip

The zip is created readable by other users and holds your API keys, so chmod 600 closes it. Copy the file off the server with rsync or scp and restore it on a new install with hermes import. For a copy of the whole server, see VPS backups.

Uninstall Hermes Agent

Remove the system service first. hermes uninstall runs without root, so it leaves the unit enabled, and systemd then restarts the missing gateway in a loop:

sudo HERMES_HOME="$HOME/.hermes" "$HOME/.local/bin/hermes" gateway uninstall --system

✓ Removed /etc/systemd/system/hermes-gateway.service
✓ System service uninstalled

Then preview and run the uninstaller. It removes the code checkout and the PATH entry and keeps ~/.hermes for a reinstall. hermes uninstall --full also deletes ~/.hermes, so run hermes backup before you use it:

hermes uninstall --dry-run
hermes uninstall

If it reports Permission denied for files in ~/.hermes/hermes-agent, the sudo commands in this tutorial left root-owned cache files there. Remove the rest with sudo rm -rf ~/.hermes/hermes-agent. For the Docker install, run docker rm -f hermes.

Troubleshoot common Hermes Agent errors

Start with hermes doctor, which reports what is missing and how to fix it. Gateway logs are in the journal: sudo journalctl -u hermes-gateway -n 50 --no-pager.

FAQ

How much RAM does Hermes Agent need?

Hermes Agent needs 1 GB of RAM and 1 CPU core at minimum, according to the official Docker guide, with 2 cores and 2 to 4 GB recommended. Browser tools raise the floor to 2 GB. A local Ollama model at the 64,000-token context Hermes needs adds more than 3 GB.

Is Hermes Agent free?

Yes. Hermes Agent is open source under the MIT License, and the installer and Docker image cost nothing. Model providers such as OpenRouter, Anthropic or Nous Portal charge your own account, and a local Ollama model runs on your server.

Should the Hermes gateway run as a system service or a user service?

Use the system service on a VPS. The Hermes messaging docs recommend it for headless hosts that should come back at boot without relying on systemd linger. A user service with linger also starts at boot and lets hermes update restart it without root. Install one of them, not both.

How do I update Hermes Agent?

Run hermes update as the user who installed it, then restart the system service with sudo, passing HERMES_HOME and the full path to hermes. Docker installs do not support hermes update: pull a newer image tag and recreate the container with the same data mount.

Can I run Hermes Agent in Docker?

Yes. The official nousresearch/hermes-agent image is a Tier 1 platform. Pin a tag such as v0.22.5, mount ~/.hermes at /opt/data, and run gateway run with a restart policy. Publish ports on 127.0.0.1 only and give the dashboard a password.

How do I open the Hermes Agent dashboard on a remote server?

Connect with ssh -L 9119:127.0.0.1:9119, run hermes dashboard --no-open on the server, and open http://127.0.0.1:9119 in your local browser. The dashboard binds to 127.0.0.1 by default and refuses a public address without a login provider.

Can Hermes Agent use a local Ollama model?

Yes. Set Hermes to a custom provider at http://127.0.0.1:11434/v1 with the Ollama model name. Hermes needs at least 64,000 tokens of context, so raise OLLAMA_CONTEXT_LENGTH and pick a model whose window reaches that size. Use it for on-demand replies on a server with more than 4 GB of RAM.

Next steps

• Hermes Agent vs OpenClaw: Key Differences for Self-Hosting
• How to Self-Host LiteLLM Proxy with Docker Compose on Ubuntu 24.04, to put several model providers behind one key and add it to Hermes as a custom endpoint
• Hermes Agent messaging gateway documentation for Discord, Slack, WhatsApp and the other platforms
• Hermes Agent releases on GitHub

See Hermes Agent VPS plans for plan sizes. Compare plans.