Hermes Agent Self-Hosted Setup: Step-by-Step

Hermes Agent self-hosting requires a Linux VPS, Docker, and 30-60 minutes of setup. You provision the server, pull the Docker image, configure your LLM provider API key, and run the agent. Most teams complete this in a single afternoon, but ongoing maintenance--monitoring logs, handling updates, managing API key rotation--consumes 5-15 hours per month.

What You'll Need: Prerequisites & Cost Estimate

Self-hosting Hermes requires a Linux server (2+ vCPU, 4+ GB RAM), Docker, git, and an LLM provider account (OpenAI, Anthropic, local LLaMA). Your total infrastructure cost ranges from $10-50/month on a VPS, plus API usage fees if you choose a managed LLM provider.

This is not a "click and deploy" platform. You are responsible for patching the OS, managing backups, securing API keys, and monitoring uptime. If your VPS goes down at 2 a.m., you handle the restart. If your Docker container runs out of disk space, you fix it.

The upside: complete data residency, no per-message charges beyond your VPS bill, and full control over which models and integrations your agent uses. The downside: you own the operational burden.

Here is what you will need before starting:

1. Linux VPS access (Ubuntu 22.04 LTS recommended, $12-50/month depending on specs)
2. SSH key (generated on your local machine)
3. Docker & Docker Compose (free, installs in minutes)
4. LLM API key (OpenAI, Claude, Cohere, or a local model)
5. Telegram/Discord/Slack bot token (if you plan to use messaging integrations)
6. Basic Linux knowledge (you can follow docs, but you will troubleshoot CLI errors)
7. Domain name + SSL certificate (optional but strongly recommended for production)

Total setup cost (first month): $12-50 VPS + API key deposit (e.g., $5-20 on OpenAI). No software licensing fees.

Choose Your VPS: Providers & Sizing

Hermes agents run on any Linux VPS. The choice depends on your budget and tolerance for support. Here is a quick comparison:

Provider	Entry Plan	vCPU	RAM	SSD	Price/Month	Strength
Hetzner Cloud	CPX11	2	4 GB	40 GB	EUR 4.50 (~$5)	Cheapest, fast I/O
Vultr	Cloud Compute	2	4 GB	60 GB	$12	Low latency, global
DigitalOcean	Droplet	2	4 GB	80 GB	$12	Managed backups available
Linode	Nanode	1	1 GB	25 GB	$5	Micro, not recommended for Hermes

For a single Hermes agent handling <100 concurrent users, a 2-vCPU/4GB RAM instance ($12-18/month) is adequate. The agent itself uses ~200-300 MB of RAM at idle; the rest is headroom for Docker, your LLM provider SDK, and logging.

If you expect >100 concurrent users or multiple agents on one server, move to 4 vCPU / 8 GB RAM ($30-50/month). Real-time messaging (Telegram webhooks) and LLM inference are I/O-heavy; extra CPU helps.

Why not the cheapest option? Hetzner is fantastic for price, but you do not get phone support or managed backups. If your VPS disappears due to account suspension or data center failure, you have no recovery path. For a production agent, spend the extra $7/month on DigitalOcean or Vultr for their support and backup infrastructure.

Local testing before VPS: If you are new to Docker, set up Hermes locally on your laptop first. This saves VPS time and lets you validate your LLM API setup.

Prepare the Host: Linux, Docker, and Dependencies

To run Hermes, you need a clean Linux environment with Docker installed and firewall rules in place. This section assumes Ubuntu 22.04 LTS (the VPS provider default on most clouds).

Step 1: SSH into your VPS and update the system

SSH in and run updates:

ssh root@your-vps-ip
apt update && apt upgrade -y
apt install -y curl git wget vim

These packages are essential. curl and wget fetch files, git clones the Hermes repo (if needed), and vim edits config files.

Step 2: Install Docker and Docker Compose

Docker is the container runtime. Compose manages multi-container setups with a single YAML file.

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Add current user to docker group
usermod -aG docker $USER

# Install Docker Compose from the official releases page

# Visit: https://github.com/docker/compose/releases

# Download the binary for your Linux architecture and place in /usr/local/bin
chmod +x /usr/local/bin/docker-compose

# Verify
docker --version
docker-compose --version

Step 3: Create a dedicated user for Hermes

Isolating the agent from root is a security best practice.

useradd -m -s /bin/bash hermes
usermod -aG docker hermes
su - hermes

This isolates Hermes from the root account. If the agent is compromised, the attacker has access only to the hermes user, not root.

Step 4: Configure the firewall

Open only the ports you need. SSH (22) for management, 8080 for the agent (internal only), and 443 for HTTPS.

# If using UFW (Ubuntu's firewall)
ufw allow 22/tcp          # SSH
ufw allow 8080/tcp        # Hermes agent (internal)
ufw allow 443/tcp         # HTTPS (for reverse proxy)
ufw enable

Do not expose port 8080 to the internet directly. You will run Hermes internally and route traffic through a reverse proxy (Nginx or Caddy) on port 443. This isolates the agent and adds SSL/TLS.

Step 5: Create directories for persistent data

Docker containers are ephemeral; if the container dies, data inside is lost. Persistent volumes mount a directory from your VPS into the container so config and logs survive restarts.

mkdir -p /home/hermes/data
mkdir -p /home/hermes/config
chmod 755 /home/hermes/data
chmod 755 /home/hermes/config

Deploy Hermes Agent: Docker Setup

Now you will pull the Hermes Docker image and start the agent. We recommend docker-compose for production because it manages environment variables, volumes, and networking in one declarative file.

Option A: Docker Compose (Recommended)

Create a file named docker-compose.yml in your /home/hermes/ directory:

version: '3.8'

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-agent
    restart: always
    ports:
      - "8080:8080"
    environment:
      HERMES_LLM_PROVIDER: openai
      HERMES_LLM_API_KEY: ${LLM_API_KEY}
      HERMES_TELEGRAM_TOKEN: ${TELEGRAM_BOT_TOKEN}
      HERMES_LOG_LEVEL: info
    volumes:
      -./data:/app/data
      -./config:/app/config
    networks:
      - hermes-net

networks:
  hermes-net:
    driver: bridge

Create a .env file in the same directory:

LLM_API_KEY=sk-your-openai-key-here
TELEGRAM_BOT_TOKEN=your-telegram-bot-token-here

Why.env files? Never hardcode API keys in docker-compose.yml. If you commit the YAML to git (even a private repo), the key is visible in the commit history forever. Use.env, add it to.gitignore, and Docker Compose reads it at runtime.

Start the agent:

docker-compose up -d

The -d flag means "detached" (background). Check logs immediately:

docker-compose logs -f

You should see output like:

hermes-agent  | [2026-08-18 10:23:45] Hermes Agent started
hermes-agent  | [2026-08-18 10:23:50] Listening on 0.0.0.0:8080
hermes-agent  | [2026-08-18 10:23:52] LLM provider initialized (OpenAI)

Option B: Direct Docker run (single command)

If you skip docker-compose, use one command. This works but is harder to maintain long-term.

docker run -d \
  --name hermes-agent \
  --restart always \
  -p 8080:8080 \
  -e HERMES_LLM_API_KEY=sk-your-openai-key \
  -e HERMES_TELEGRAM_TOKEN=your-telegram-bot-token \
  -v /home/hermes/data:/app/data \
  -v /home/hermes/config:/app/config \
  nousresearch/hermes-agent:latest

Stick with docker-compose.

Step 2: Run the Setup Wizard

On first start, Hermes runs an interactive setup wizard. Access it via:

docker-compose exec hermes-agent hermes setup

The wizard asks:

1. LLM Model: Which model? (GPT-4, Claude 3, local LLaMA, etc.)
2. Telegram Bot Token: Your bot's API token (if using Telegram)
3. Allowed Users: Telegram/Discord/Slack user IDs allowed to message the agent (security gate)
4. Base Prompt: System instructions for the agent (optional)

Save these settings. They persist in /home/hermes/config/.

Step 3: Restart the container to apply configuration

docker-compose restart hermes-agent

At this point, your Hermes agent is running. It is not yet accessible from the internet; it listens only on localhost:8080 inside the VPS.

Configure Messaging & Security

Your Hermes agent is running but isolated. Now you will set up messaging (Telegram, Discord, or Slack webhooks), configure a reverse proxy with SSL/TLS, and lock down API keys and firewall rules.

Part 1: Telegram Webhook Setup

If you are using Telegram, Telegram sends messages to your agent via HTTP webhook. Hermes listens on port 8080 internally; you need a reverse proxy on 443 to accept Telegram's HTTPS traffic.

First, set your Telegram webhook using the Telegram Bot API. Use your domain name in place of the placeholder:

# Set webhook to your domain (replace YOUR_DOMAIN and YOUR_BOT_TOKEN with actual values)
curl -X POST https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook \
  -H "Content-Type: application/json" \
  -d '{"url":"https://YOUR_DOMAIN/webhook/telegram"}'

Telegram will send POST requests to your webhook endpoint whenever your bot receives a message.

Part 2: Reverse Proxy with Nginx or Caddy

A reverse proxy sits between the internet and your Hermes agent. It terminates SSL/TLS, routes traffic, and hides the internal port (8080).

Option A: Caddy (easier)

Install Caddy and let it manage SSL automatically:

apt install -y caddy

Create /etc/caddy/Caddyfile (replace YOUR_DOMAIN):

YOUR_DOMAIN {
  reverse_proxy localhost:8080 {
    header_upstream Host {host}
    header_upstream X-Real-IP {remote_ip}
  }
}

Caddy automatically provisions an SSL certificate from Let's Encrypt. Start Caddy:

systemctl restart caddy

Test by visiting your domain with HTTPS.

Option B: Nginx (more control, more config)

Install Nginx:

apt install -y nginx

Create /etc/nginx/sites-available/hermes (replace YOUR_DOMAIN):

upstream hermes_backend {
  server localhost:8080;
}

server {
  listen 80;
  server_name YOUR_DOMAIN;
  return 301 https://$server_name$request_uri;
}

server {
  listen 443 ssl http2;
  server_name YOUR_DOMAIN;

  ssl_certificate /etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem;

  location / {
    proxy_pass http://hermes_backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 60s;
  }
}

Enable the site:

ln -s /etc/nginx/sites-available/hermes /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx

Provision SSL with Let's Encrypt:

apt install -y certbot python3-certbot-nginx
certbot certonly --standalone -d YOUR_DOMAIN

Part 3: Secure Your Hermes Setup

Now that Hermes is behind a reverse proxy on port 443, lock down the internal port:

# Only allow localhost traffic on port 8080
ufw delete allow 8080/tcp
ufw allow from 127.0.0.1 to 127.0.0.1 port 8080
ufw allow from ::1 to ::1 port 8080

For more details on Docker security and production deployments, see Opsily's guide to Hermes Agent Docker: Deploy & Manage in Containers.

Part 4: Store and Rotate API Keys

Never hardcode keys in your code or config. Use environment variables (Docker.env files) and rotate them every 90 days.

Set a reminder:

# Add to root's crontab
(crontab -l 2>/dev/null; echo "0 0 1 */3 * echo 'Rotate API keys for Hermes agent'") | crontab -

If an API key is leaked, immediately revoke it in your LLM provider dashboard (OpenAI, Anthropic) and update the.env file.

For teams with sensitive workloads (e.g., analyzing GDPR data), self-hosted Hermes on EU infrastructure ensures data residency compliance. This is a critical differentiator from cloud-hosted alternatives.

Verify & Test Your Installation

Your agent is running, reverse proxy is live, and Telegram webhook is set. Now verify it works.

Check container health

docker-compose logs

Look for no errors (warnings are OK). If you see "LLM connection failed" or "Telegram authentication error," fix these before proceeding.

Send a test Telegram message

Open Telegram, find your bot, and send: "Hello, what is 2+2?"

Wait 2-5 seconds. Your agent should respond with "The answer is 4."

If nothing happens:

1. Check the webhook is set correctly by querying the Telegram Bot API.
2. Check reverse proxy logs to see if requests arrive.
3. Check Hermes logs for parse errors or API failures.

Common errors and fixes:

Error	Cause	Fix
"Connection refused on port 8080"	Docker container not running	docker-compose up -d
"webhook URL mismatch"	Telegram webhook and config don't match	Re-run setup wizard
"invalid API key"	LLM_API_KEY is wrong	Check.env file, verify key in provider dashboard
"timeout contacting LLM"	Network or API provider down	Verify curl to LLM API works independently
"disk full"	Container logs or data filling the VPS	Implement log rotation; see next section

After a successful test message, your Hermes setup is complete and working.

Maintain & Upgrade

A running Hermes agent requires minimal maintenance, but a few tasks prevent outages and keep it secure.

Weekly log review

docker-compose logs | grep -i error

Errors here are actionable. Warnings can be ignored unless they accumulate.

Monthly Docker image updates

Every 30 days, pull the latest Hermes image:

docker-compose pull
docker-compose restart hermes-agent

This picks up security patches and bug fixes. Test in staging first if the agent is business-critical.

Monitor API usage and costs

Set up alerts in your LLM provider dashboard (OpenAI, Anthropic, Cohere). Set a monthly budget limit so unexpected usage doesn't spike your bill. A runaway agent (stuck in a loop making API calls) can cost $100+ in a day.

Backups

Backup your Hermes config and data weekly:

# Add to crontab
0 2 * * 0 tar -czf /backups/hermes-backup.tar.gz /home/hermes/

This creates a compressed backup every Sunday at 2 a.m. Copy backups to a second VPS or cloud storage (S3, Backblaze).

SSL certificate renewal

Let's Encrypt certificates expire every 90 days. Caddy renews automatically; Nginx + Certbot also renew automatically. Check:

certbot renew --dry-run

If renewal fails (e.g., domain DNS is broken), Telegram webhooks stop working and your agent becomes unreachable.

Monitoring and alerting (optional but recommended)

For production agents, set up log monitoring. This is beyond the scope of a basic setup, but it prevents you from missing critical failures at 2 a.m.

When to Stop Self-Hosting: The Managed Alternative

Self-hosting saves money but costs time. Do the math:

• Infrastructure: $12-50/month (VPS)
• Setup: 2-3 hours (one-time)
• Maintenance: 5-15 hours/month (monitoring, updates, backups, troubleshooting)
• Total annual effort: 60-180 hours

If you earn $100/hour, that is $6,000-18,000 in hidden cost annually, on top of the $144-600 VPS bill.

When self-hosting makes sense: You have in-house DevOps/SRE expertise, your data residency is a hard requirement (GDPR, HIPAA, SOC2), you run multiple agents and amortize the management cost, or you want to tinker with the agent source code.

When managed hosting makes sense: You want to focus on building with Hermes, not maintaining infrastructure; you need guaranteed 99.9% uptime (managed providers have SLAs); you want automatic backups, monitoring, and failover; or you prefer predictable billing with no surprise API cost overages.

Opsily's managed Hermes Agent hosting removes the operational burden. You deploy your agent via a web dashboard, Opsily handles the VPS, Docker, SSL, backups, and monitoring. You focus on building. The convenience premium is typically $50-200/month on top of your API costs, which pays for itself in time saved if your hourly rate exceeds $50.

If after reading this tutorial you felt: "this is a lot of steps," managed hosting is the right choice. No shame in that. Infrastructure is a means to an end; if it is not your business, outsource it.

Frequently Asked Questions

Can I run Hermes on my laptop instead of a VPS?

Yes, for testing. Your laptop is not always online, so the Telegram webhook will fail when your laptop sleeps or loses internet. For a production agent that handles real messages 24/7, you need a VPS or managed hosting.

What if my VPS gets hacked?

An attacker with VPS access can read your LLM API keys, impersonate your agent, and rack up API charges. Rotate all API keys immediately and check your API usage for signs of abuse. Use managed hosting if you cannot guarantee physical security or access control for your infrastructure.

Can I run Hermes on Kubernetes?

Yes. If you have K3s or managed Kubernetes (EKS, GKE), deploy Hermes as a Helm chart. This is overkill for a single agent but makes sense at scale (e.g., >10 agents, enterprise load balancing). The Nous Research docs have a Kubernetes example.

How much do API calls cost?

Pricing varies by model and provider. OpenAI's GPT-4 costs ~$0.03 per 1,000 input tokens and ~$0.06 per 1,000 output tokens. A typical Hermes message (100 tokens in, 50 tokens out) costs ~$0.005. If your agent handles 1,000 messages/day, that is ~$5/day or ~$150/month. Cheaper models (GPT-3.5 Turbo) cost 1/10th as much.

Can I use a local LLM instead of OpenAI?

Yes. Hermes supports Ollama, LLaMA 2, Mistral, and other open-source models. Running a local model saves API costs but requires 8+ GB of VRAM (a higher-end VPS). Inference is also slower, so response latency increases from <1 second to 5-10 seconds.

How do I upgrade Hermes without downtime?

Use a blue-green deployment: spin up a second Hermes container, test it, then switch traffic via the reverse proxy. This requires load balancing (HAProxy or Nginx upstream). For a single agent, a 30-second restart window is acceptable.

Should I open-source my agent config?

No, unless you want to leak your LLM API key. Even if you clean the config file, commit history retains secrets. Use private repos and never commit.env files.

The Bottom Line

Hermes Agent self-hosting is straightforward: provision a VPS, install Docker, pull the image, configure your LLM API key and messaging webhook, and run the setup wizard. Most teams complete it in 2-3 hours.

The catch is ongoing maintenance. You own monitoring, log management, security patching, backup automation, and API cost management. If downtime during your sleep is unacceptable, or if you value engineering time over infrastructure cost, managed hosting skips the operational pain.

Start with self-hosting if you are a builder tinkering with Hermes. Move to managed hosting if you are running it in production and do not have a DevOps team. Either way, Hermes is now in your toolkit.