How To Setup Hermes Agent on VPS 2026

Previously, I had covered how to install OpenClaw and Paperclip. Today, I will install and set up the Hermes agent on an Ubuntu VPS.

I will use Docker and Traefik as a reverse proxy with a free SSL certificate from Let’s Encrypt. At the end, you will be able to access your own self-hosted AI agent and chat with it.

Let’s get started.

What is Hermes Agent?

The self-improving AI agent built by Nous Research. It’s the only agent with a built-in learning loop; it creates skills from experience, improves them during use, nudges itself to persist in knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions.

You can talk to it from Telegram, Discord, WhatsApp, and 15+ other platforms while it runs 24/7 on your VPS.

What You Need Before Starting

• A VPS running Ubuntu 22.04 or 24.04 (minimum 2GB RAM, 2 CPU cores)
• A domain name pointing to your VPS IP
• Root SSH access to your server
• An API key from OpenAI, Anthropic, or OpenRouter

Phase 1 — Prepare Your VPS

In the tutorial, I am going to use Kamatera, which comes with a 30-day trial.

Step 1: Update Your Server
SSH into your VPS and run:

bash
apt update && apt upgrade -y
apt install -y curl wget git nano apache2-utils ufw

Step 2: Configure Firewall

bash
ufw allow ssh
ufw allow 80
ufw allow 443
ufw enable

Step 3: Install Docker

bash
curl -fsSL https://get.docker.com | bash
systemctl enable docker
systemctl start docker

Verify it installed correctly:

bash
docker --version
docker compose version

You should see Docker version 27.x.x and Docker Compose v2.x.x.

Phase 2 — Set Up DNS

Go to your DNS provider (Cloudflare, Namecheap, etc.) and add these A records pointing to your VPS IP:

Find your VPS IP with:

bash
curl ifconfig.me

Wait 2–5 minutes and then verify DNS is live:

bash
ping hermes.yourdomain.com

Press Ctrl+C to stop the ping.

Phase 3 — Install Traefik

Traefik is a reverse proxy. It sits in front of all your services and automatically issues free SSL certificates from Let’s Encrypt. This is what makes https://hermes.yourdomain.com work.

Step 1: Create Traefik Folder

bash
mkdir -p /opt/traefik
cd /opt/traefik
touch acme.json
chmod 600 acme.json

The chmod 600 is critical. Traefik will refuse to start without it.

Verify it looks correct:

bash
ls -la /opt/traefik/
You should see -rw------- next to acme.json.

 

Step 2: Create the Docker Network

All your services will communicate through this shared network:

bash
docker network create proxy

Step 3: Generate a Dashboard Password

Replace yourpassword with something strong:

bash
htpasswd -nb admin yourpassword | sed -e 's/\$/\$\$/g'

Copy the output. It will look like:

admin:$$apr1$$i6SAvaHG$$DIgtvaY.7ieJaOD9SoHbU.

 

Step 4: Create the Traefik docker-compose.yml

bash
nano /opt/traefik/docker-compose.yml

Paste this and replace the 3 marked values:

yaml
services:
traefik:
image: traefik:v3
container_name: traefik
restart: unless-stopped
command:
- --log.level=INFO
- --api.dashboard=true
- --api.insecure=false
- --providers.docker=true
- --providers.docker.exposedbydefault=false
- --providers.docker.network=proxy
- --entrypoints.web.address=:80
- --entrypoints.websecure.address=:443
- --entrypoints.web.http.redirections.entrypoint.to=websecure
- --entrypoints.web.http.redirections.entrypoint.scheme=https
- --entrypoints.web.http.redirections.entrypoint.permanent=true
- --certificatesresolvers.letsencrypt.acme.httpchallenge=true
- --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web
- --certificatesresolvers.letsencrypt.acme.email=you@email.com # ← CHANGE THIS
- --certificatesresolvers.letsencrypt.acme.storage=/acme.json
ports:
- "80:80"
- "443:443"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- ./acme.json:/acme.json
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.dashboard.rule=Host(`traefik.yourdomain.com`)" # ← CHANGE THIS
- "traefik.http.routers.dashboard.entrypoints=websecure"
- "traefik.http.routers.dashboard.tls.certresolver=letsencrypt"
- "traefik.http.routers.dashboard.service=api@internal"
- "traefik.http.routers.dashboard.middlewares=auth"
- "traefik.http.middlewares.auth.basicauth.users=admin:$$apr1$$PASTE$$YOURHASHEDPASSWORDHERE" # ← CHANGE THIS

networks:
proxy:
external: true

Save with Ctrl+O → Enter → Ctrl+X.

Step 5: Start Traefik

bash
cd /opt/traefik
docker compose up -d
docker compose logs -f
Look for these lines:

INF Starting provider *docker.Provider
INF Traefik entrypoint started {"address": ":443"}
INF Register... providerName=letsencrypt.acme

Press Ctrl+C to stop watching logs. Traefik keeps running in the background.

Now open https://traefik.yourdomain.com in your browser. You should see the Traefik dashboard login screen. Log in with username admin and the password you set.

Phase 4 — Install Hermes Agent

Step 1: Create Folders

bash
mkdir -p /opt/hermes
mkdir -p ~/.hermes
chmod 777 ~/.hermes

Step 2: Run the Setup Wizard
This downloads the Hermes image (2.4GB) and launches the setup wizard:

bash
docker run -it --rm \
-v ~/.hermes:/opt/data \
nousresearch/hermes-agent setup

The wizard will ask for:

Your LLM API key (OpenAI, Anthropic, OpenRouter, etc.)
A messaging platform (Telegram is recommended — get a bot token from @BotFather)
Everything gets saved to ~/.hermes/.env and ~/.hermes/config.yaml. You only need to do this once.

Step 3: Create the Hermes docker-compose.yml

bash
nano /opt/hermes/docker-compose.yml

Paste this:

 
yaml
services:
hermes:
image: nousresearch/hermes-agent:latest
container_name: hermes
restart: unless-stopped
command: gateway run
volumes:
- ~/.hermes:/opt/data
networks:
- hermes-net
- proxy
deploy:
resources:
limits:
memory: 4G
cpus: "2.0"
labels:
- "traefik.enable=true"
- "traefik.http.routers.hermes-api.rule=Host(`hermes.yourdomain.com`) && PathPrefix(`/v1`)"
- "traefik.http.routers.hermes-api.entrypoints=websecure"
- "traefik.http.routers.hermes-api.tls.certresolver=letsencrypt"
- "traefik.http.services.hermes-api.loadbalancer.server.port=8642"

dashboard:
image: nousresearch/hermes-agent:latest
container_name: hermes-dashboard
restart: unless-stopped
command: dashboard --host 0.0.0.0 --insecure
volumes:
- ~/.hermes:/opt/data
environment:
- GATEWAY_HEALTH_URL=http://hermes:8642
networks:
- hermes-net
- proxy
depends_on:
- hermes
deploy:
resources:
limits:
memory: 512M
cpus: "0.5"
labels:
- "traefik.enable=true"
- "traefik.http.routers.hermes-dashboard.rule=Host(`hermes.yourdomain.com`)"
- "traefik.http.routers.hermes-dashboard.entrypoints=websecure"
- "traefik.http.routers.hermes-dashboard.tls.certresolver=letsencrypt"
- "traefik.http.services.hermes-dashboard.loadbalancer.server.port=9119"

networks:
hermes-net:
driver: bridge
proxy:
external: true

Save with Ctrl+O → Enter → Ctrl+X.

Step 4: Start Hermes

bash
cd /opt/hermes
docker compose up -d 

Verify all containers are running:

bash
docker ps

You should see 3 containers running — traefik, hermes, and hermes-dashboard.

Phase 5 — Verify Everything Works

Open your browser and visit:

Useful Commands to Manage Hermes

bash
# View live logs
docker compose -f /opt/hermes/docker-compose.yml logs -f

# Restart Hermes
docker compose -f /opt/hermes/docker-compose.yml restart

# Update to latest version
docker pull nousresearch/hermes-agent:latest
docker compose -f /opt/hermes/docker-compose.yml up -d

# Open interactive CLI inside running container
docker exec -it hermes /opt/hermes/.venv/bin/hermes

Troubleshooting

FAQ

1. Do I need coding knowledge to install Hermes Agent on a VPS?

Not really. You just need to copy and paste commands into your terminal. The guide above walks you through every single step. Even if you have never used Docker before, you can follow along.

2. Which VPS is best for running Hermes Agent?

You need at least 2GB RAM and 2 CPU cores. If you plan to use browser automation features inside Hermes, go for 4GB RAM. A $6–$12/month VPS from providers like DigitalOcean, Hetzner, or Contabo works well.

3. Is Hermes Agent free to use?

Hermes Agent itself is completely free and open source (MIT license). You only pay for the LLM API usage from your chosen provider — OpenAI, Anthropic, or OpenRouter. If you use a local model, it is completely free.

4. Can I use Hermes Agent with Telegram?

Yes. During the setup wizard, you can connect it to Telegram using a bot token from @BotFather. After that, you can chat with your agent directly from Telegram while it runs 24/7 on your VPS.

5. What happens to my data if I restart the VPS?

Nothing is lost. All your config, API keys, sessions, memories, and skills are stored in the ~/.hermes folder on your host machine — not inside the container. The container is stateless and can be restarted or updated without losing anything.