Setting up a self-hosted AI agent that runs 24/7 on your own server changes how you work with automation. You get full data ownership, customizable behavior, and zero per-message costs from middleman services. Hermes Agent is an open-source AI agent framework by Nous Research that remembers context across sessions, executes scheduled jobs, and connects to Telegram, Discord, and WhatsApp. This guide shows you exactly how to install Hermes Agent on Ubuntu 26.04 with three deployment methods, security hardening, and troubleshooting for common errors.

Prerequisites for Installing Hermes Agent on Ubuntu 26.04

Before running any commands, verify your system meets these requirements:

• Operating System: Ubuntu 26.04 LTS (Resolute Raccoon) released April 23, 2026
• Python Version: 3.11 or higher (the installer provisions this automatically via uv)
• Git: Must be pre-installed (the only manual prerequisite the installer does not handle)
• Node.js: Required for browser tooling and WhatsApp bridge features
• RAM: Minimum 8 GB recommended for smooth LLM inference calls
• Disk Space: At least 10 GB free if using Docker containerized deployment
• User Permissions: SSH access as a non-root user (do not install Hermes as root)
• API Key: From an LLM provider (OpenAI, Anthropic, OpenRouter, or Vultr Serverless Inference)

Ubuntu 26.04 includes GNOME 50, Linux kernel 7.0, and Wayland-only desktop by default. The server image comes with apt package manager and systemd for service management, which makes running Hermes as a persistent background service straightforward.

What Is Hermes Agent and Why Self-Host on Ubuntu 26.04

Hermes Agent is developed by Nous Research, the same team behind the Hermes family of open-weight LLMs. It runs as a persistent systemd service on Linux, meaning it stays active continuously rather than requiring you to manually restart it after each use.

The agent supports any OpenAI-compatible LLM provider. You can use OpenAI’s GPT models, Anthropic’s Claude, OpenRouter’s 200+ model marketplace, or self-hosted options like Ollama and vLLM.

Self-hosting on Ubuntu 26.04 gives you three critical advantages over cloud-only solutions:

1. Data ownership: Your conversation history and memory stay on your server, not in a vendor’s database
2. Customizable agent behavior: You control skills, cron jobs, and tool access without vendor restrictions
3. No middleman overhead: Direct API calls to your LLM provider eliminate per-message fees from SaaS platforms

Ubuntu 26.04’s systemd integration and apt ecosystem make it the most stable platform for long-running Hermes deployments compared to Windows or macOS. The native service manager handles automatic restarts on failure, and apt ensures dependency consistency across updates.

Method 1: Quick Install via Official One-Line Installer (Recommended for Most Users)

This is the fastest path. The official installer script handles Python 3.11+, Node.js, uv package manager, repository cloning, and PATH configuration automatically. You only need to install Git manually before running it.

Step 1: Update Your System and Install Git

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

The apt update command refreshes your package index from Ubuntu’s repositories. Running apt upgrade -y before installing anything prevents dependency conflicts where outdated libc or libssl versions break the installer mid-run. Git is the only dependency the official Hermes installer does not provision itself. Curl is needed to download the installer script.

Expected output after running these commands:

Reading package lists... Done
Building dependency tree... Done
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
git is already the newest version (2.43.0-1).
curl is already the newest version (8.5.0-2).

If Git is not installed, you will see:

The following NEW packages will be installed:
  git curl
0 upgraded, 2 newly installed, 0 to remove and 0 not upgraded.

Step 2: Run the Official Installer Script

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The -fsSL flags on curl mean specific things that prevent installation failures:

• -f: Fail silently on HTTP errors (does not output a 404 page)
• -s: Suppress the progress meter (no download percentage shown)
• -L: Follow HTTP redirects automatically
• -S: Show server response errors

This prevents a truncated or error-page response from being piped into bash and executed. The script auto-detects your OS, provisions Python 3.11+ via uv, installs Node.js, clones the repository to ~/.hermes/hermes-agent, and creates the hermes CLI symlink in ~/.local/bin.

During installation, you will see output like:

[INFO] Detected OS: Ubuntu 26.04
[INFO] Installing uv package manager...
[INFO] Provisioning Python 3.11.9 via uv...
[INFO] Cloning hermes-agent repository...
[INFO] Creating hermes CLI symlink...
[SUCCESS] Hermes Agent installed successfully. Run 'source ~/.bashrc' to use.

If you see an error about uv not being found, your system may have an outdated curl version. Update curl first:

sudo apt update && sudo apt install -y curl

Step 3: Reload Your Shell to Apply PATH Changes

source ~/.bashrc

The installer appends ~/.local/bin to your PATH variable in ~/.bashrc. Without sourcing it, your current terminal session will not find the hermes command because PATH changes only apply to new shells or when explicitly loaded. This is a common mistake that causes “command not found” errors in the next step.

If you forget this step, you can verify by running:

echo $PATH

You should see /home/youruser/.local/bin in the output. If it is missing, run source ~/.bashrc again.

Step 4: Verify the Installation Was Successful

hermes --version

This command checks that the hermes CLI is accessible and returns the installed version number. A missing version output means the CLI symlink was not created or PATH was not updated correctly. Catching this now saves you from debugging configuration errors later when running hermes setup.

Expected output:

hermes version 0.14.2

If you see hermes: command not found, run source ~/.bashrc again and check that ~/.local/bin is in your PATH with echo $PATH.

Step 5: Run the Setup Wizard to Configure Your LLM Provider

hermes setup

The setup wizard asks you to choose an LLM provider and enter your API key. Supported providers include:

• OpenAI (GPT-4o, GPT-4o Mini)
• Anthropic (Claude 3.5 Sonnet)
• OpenRouter (200+ models including free-tier options)
• Vultr Serverless Inference
• Any OpenAI-compatible endpoint

The wizard saves your API key to ~/.hermes/.env with proper file permissions. For cost-conscious deployments, OpenRouter gives access to free-tier models like Nous Research’s own Nvidia Nemotron 3 Ultra.

Navigate the wizard options using up and down arrow keys, then press Enter to confirm. For terminal backend selection, choose local for direct shell access or docker for sandboxed file system access (recommended for security).

After setup completes, you will see:

[SUCCESS] LLM provider configured. Your API key is saved to ~/.hermes/.env
[SUCCESS] Gateway ready. Run 'hermes' to start the terminal interface.

Step 6: Start the Hermes Gateway and Test Your Agent

hermes

This command starts the Hermes gateway, which is the persistent background process that handles all agent requests. The gateway connects to your configured LLM provider and waits for commands from the terminal, Telegram, or the web dashboard.

You will see output like:

[INFO] Starting Hermes Gateway v0.14.2
[INFO] Connected to LLM provider: OpenRouter
[INFO] Memory loaded: 1,247 tokens from previous sessions
[INFO] Gateway ready. Type a message or use '/' commands.

Type a test message like “What is 25 multiplied by 4?” to confirm the agent responds. If you get an error about the LLM not responding, re-run hermes setup and verify your API key is correct.

Method 2: Manual Installation (For Advanced Users and Contributors)

Use this path when you need a specific branch, plan to contribute code, or want to pin Hermes to a specific commit for a production environment. This gives you full control over versioning.

Step 1: Clone the Repository with Git

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

Cloning gives you the full Git history, allowing you to roll back to a previous commit if a new release breaks your workflow. The official installer does not expose this level of version control. You can check available branches with git branch -a and switch to a specific version with git checkout <commit-hash>.

Step 2: Initialize the mini-swe-agent Submodule

git submodule update --init mini-swe-agent

mini-swe-agent is the terminal backend that gives Hermes the ability to execute shell commands on your system. Without this submodule, the agent can communicate but cannot interact with your file system or run scripts. Forgetting this step is the most common cause of “tool unavailable” errors after a manual install.

Expected output:

Submodule path 'mini-swe-agent': checked out 'commit-hash'

Step 3: Install uv and Create a Python Virtual Environment

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv .venv --python 3.11
source .venv/bin/activate

uv is a Rust-based package manager that resolves and installs Python dependencies 10-100x faster than pip. Creating an isolated virtual environment means Hermes’s dependencies never conflict with other Python tools on your server. The --python 3.11 flag ensures you use the exact version Hermes requires, as it does not support Python 3.12 yet.

If you see an error about uv not being found after installation, add it to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Step 4: Install Hermes Dependencies with uv

uv pip install -e ".[all,dev]"
uv pip install -e "./mini-swe-agent"

The -e flag means “editable” mode, which installs the package in development mode. This lets you edit Hermes source files and see changes reflected immediately without reinstalling the package. The [all,dev] extra installs all optional dependencies including web search, voice output, and Discord integration.

Installation takes 2-5 minutes depending on your network speed. You will see progress like:

Resolving dependencies... Done
Installing packages...
  ━━━━━━━━━━━━━━━━━━━━━━━━━━ 142/142 packages

Step 5: Create the CLI Symlink and Update PATH Permanently

mkdir -p ~/.local/bin
ln -sf "$(pwd)/.venv/bin/hermes" ~/.local/bin/hermes
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

The symlink decouples the hermes command from the virtual environment’s activation state. This means you can run hermes from any directory without manually activating .venv first. The echo command adds the PATH export to ~/.bashrc so it persists across terminal sessions.

Verify the symlink works:

hermes --version

Method 3: Docker Compose Deployment (Best for Production VPS)

This is the best approach for VPS deployments where you want automatic HTTPS via Traefik, process isolation, and easy updates without affecting your host system. Docker also sandbox’s Hermes’s terminal access for security.

Step 1: Install Docker Engine from the Official Repository

sudo apt install apt-transport-https ca-certificates curl -y
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Installing Docker from its official repository guarantees you get Docker Engine v25+ with docker-buildx-plugin and docker-compose-plugin included. The docker.io package in Ubuntu’s default repos lags significantly behind in version and often ships without Compose v2, which is required for Hermes.

Verify Docker is installed:

docker --version
docker compose version

Expected output:

Docker version 27.3.1, build 63ce5c1
docker-compose version 2.29.6

Step 2: Add Your User to the Docker Group

sudo usermod -aG docker $USER
newgrp docker

Without this, every docker command requires sudo. More importantly, running Hermes Agent as root inside Docker breaks the security model. Adding your user to the docker group allows rootless container management while keeping system privileges intact. You must log out and log back in, or run newgrp docker, for this to take effect.

Test that it works:

docker run --rm hello-world

If you see “Got permission denied while trying to connect to the Docker daemon”, run newgrp docker again.

Step 3: Create Project Directory and Environment File

mkdir -p ~/hermes/data
cd ~/hermes
nano .env

Add these lines to .env:

DOMAIN=hermes.yourdomain.com
LETSENCRYPT_EMAIL=you@example.com

Storing sensitive values in .env instead of hardcoding them in docker-compose.yml means you can commit your Compose file to version control without leaking your domain and email. Traefik reads these variables at runtime for SSL certificate provisioning.

Save and exit nano by pressing Ctrl+X, then Y, then Enter.

Step 4: Generate Dashboard Credentials with Bcrypt Hashing

docker run --rm httpd:2.4-alpine htpasswd -nbB admin 'your_secure_password' > .htpasswd

Bcrypt hashing (-B flag) is used here instead of the default MD5 because MD5-based HTTP basic auth credentials can be brute-forced trivially. This one command creates a properly hashed credential file without installing apache2-utils permanently on your host. The admin username and your_secure_password will be your web dashboard login.

Verify the file was created:

cat .htpasswd

You should see output like:

admin:$2y$05$random-hashed-password...

Step 5: Open Firewall Ports and Deploy with Docker Compose

sudo ufw allow 80/tcp && sudo ufw allow 443/tcp
docker compose up -d
docker compose ps

Ports 80 and 443 must be open before Traefik starts, because Let’s Encrypt’s TLS-ALPN-01 challenge requires port 443 to be reachable from the public internet to issue your SSL certificate. Without this, HTTPS provisioning will silently fail and Hermes will remain inaccessible. The -d flag runs containers in detached mode.

Check container status:

NAME                STATUS
hermes-gateway      running (14 days)
hermes-traefik      running (14 days)

Visit https://hermes.yourdomain.com in your browser. If you see a “502 Bad Gateway” error, wait 2-3 minutes for Let’s Encrypt to issue your certificate.

Configure Hermes Agent on Ubuntu 26.04 for Telegram Integration

Connecting Telegram gives you persistent mobile access to your agent from anywhere without exposing your server’s web UI publicly. It also supports file transfers, voice messages, and inline commands.

Step 1: Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send the message /newbot
3. Choose a bot name (e.g., “My Hermes Agent”)
4. Choose a username (e.g., “my_hermes_agent_bot”)
5. BotFather returns a token like 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

Copy this token. You will need it for the next step.

Step 2: Add the Bot Token to Your Configuration

For native installs:

nano ~/.hermes/.env

Add:

TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

For Docker installs:

nano ~/hermes/.env

Add the same line.

Set proper file permissions:

chmod 600 ~/.hermes/.env

This ensures only your user can read the file. Storing secrets with chmod 600 prevents other users on your system from accessing your API keys.

Step 3: Pair Your Bot with the Gateway

Run hermes to start the gateway, then send the pairing code it displays to your bot in Telegram. Use DM pairing codes instead of hardcoding user IDs for security. The gateway will confirm pairing when you send the code.

You will see:

[INFO] Send this code to your bot in Telegram: ABCD-1234-EFGH
[SUCCESS] Bot paired. You can now chat with Hermes from Telegram.

Troubleshooting Common Hermes Agent Installation Errors

Even with careful following of these steps, you might encounter issues. Here are the most common errors and their fixes.

Error 1: “hermes: command not found”

Cause: PATH variable does not include ~/.local/bin

Fix:

source ~/.bashrc
echo $PATH

Check that /home/youruser/.local/bin appears in the output. If it is missing, add it manually:

export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Error 2: HTTPS Certificate Not Provisioning (502 Bad Gateway)

Cause: Port 443 blocked by firewall

Fix:

sudo ufw allow 443/tcp
sudo ufw status

Wait 2-3 minutes after opening the port. Let’s Encrypt needs time to issue the certificate. Check Traefik logs:

docker compose logs traefik

Error 3: mini-swe-agent Tool Unavailable

Cause: Submodule not initialized during manual install

Fix:

cd hermes-agent
git submodule update --init mini-swe-agent
hermes

This is the most common error after manual installation. The agent cannot execute shell commands without this backend.

Error 4: Docker Permission Denied

Cause: User not in docker group

Fix:

sudo usermod -aG docker $USER
newgrp docker
docker run --rm hello-world

You must run newgrp docker or log out and back in for the group change to take effect.

Error 5: LLM Not Responding After Setup

Cause: API key missing, incorrect, or wrong provider selected

Fix:

cat ~/.hermes/.env
hermes setup

Re-run the setup wizard and verify your API key is correct. Check that the provider you selected matches the key format (OpenAI keys start with sk-, Anthropic keys are 32 characters).

Keep Hermes Agent Updated Regularly

hermes update

This single command updates the local installation, refreshes Python packages, and syncs included skills. Your personal configuration in ~/.hermes/config.yaml and API keys in ~/.hermes/.env are preserved through updates. The Hermes team releases security patches frequently, and hermes update is a core security practice, not just a feature enhancement.

For Docker deployments:

docker compose pull
docker compose up -d

[su_box title=”VPS Manage Service Offer” style=”bubbles” box_color=”#000000″ radius=”10″]If you don’t have time to do all of this stuff, or if this is not your area of expertise, we offer a service to do “VPS Manage Service Offer”, starting from $10 (Paypal payment). Please contact us to get the best deal![/su_box]