AI Agents

How to self-host Hermes Agent on a VPS

Hermes, by Nous Research, is an MIT-licensed autonomous AI agent that runs locally or on your own server. Self-hosting gives you full data ownership, no vendor lock-in, and the freedom to choose any LLM backend. This guide walks you through provisioning a VPS, installing Hermes, configuring a provider, wiring up Telegram, and running it as a resilient systemd service.

Prerequisites

A VPS running Ubuntu 22.04+ or Debian 12
Minimum 2 GB RAM and 10 GB disk (4 GB RAM / 2 vCPU recommended for comfortable headroom)
Root or sudo SSH access
An API key from one of: Nous Portal, OpenRouter, or OpenAI
A Telegram bot token (optional but recommended for easy mobile access)

Why self-host?

When you run Hermes on your own VPS, your conversations and tool outputs never touch a third-party platform. You own the process, the logs, and the storage. You can also pin a specific Hermes version and update on your schedule — no surprise breaking changes.

Step 1 — System dependencies

Hermes requires Python 3.11+, Node.js, ripgrep, ffmpeg, and git. Run the following on your VPS:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git ripgrep ffmpeg python3.11 python3.11-venv python3-pip curl

# Install Node.js 20 LTS via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Verify
python3.11 --version   # Python 3.11.x
node --version         # v20.x.x
rg --version           # ripgrep x.y.z

Step 2 — Install Hermes

Nous Research provides an official install script that clones the repo, sets up a Python virtual environment, and installs all Node and Python dependencies:

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

The script installs Hermes into ~/.hermes by default and adds the hermes command to your PATH. If you prefer a manual install, clone directly:

git clone https://github.com/NousResearch/hermes-agent.git ~/hermes-agent
cd ~/hermes-agent
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
npm install

Step 3 — Configure your LLM provider

Hermes is BYOK (Bring Your Own Key). It supports Nous Portal, OpenRouter, and OpenAI-compatible APIs. Copy the example config and add your key:

# ~/.hermes/config.env  (or the path shown by the installer)
LLM_PROVIDER=nous
NOUS_API_KEY=your_nous_portal_key_here
# Model: hermes-3-70b  (or latest Hermes model on the portal)

Step 4 — Connect Telegram (recommended)

Telegram gives you a mobile-friendly interface to interact with Hermes from anywhere. Create a bot via @BotFather in Telegram, then add the token to your config:

# In ~/.hermes/config.env
TELEGRAM_BOT_TOKEN=123456789:ABCdef...
# Optional: restrict to your Telegram user ID
TELEGRAM_ALLOWED_USER_IDS=987654321

Once configured, Hermes will register the webhook automatically on first start. Send your bot a message and it will respond through the same agent loop.

Step 5 — Run as a systemd service

Running Hermes as a systemd unit means it starts on boot, restarts on crash, and writes logs to journald:

sudo tee /etc/systemd/system/hermes.service > /dev/null <<'EOF'
[Unit]
Description=Hermes AI Agent (Nous Research)
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/.hermes
EnvironmentFile=/home/ubuntu/.hermes/config.env
ExecStart=/home/ubuntu/.hermes/.venv/bin/python -m hermes
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable hermes
sudo systemctl start hermes
sudo systemctl status hermes

Tail the logs with journalctl -u hermes -f. You should see the agent report it is connected and waiting for input.

Step 6 — Backups and updates

Back up your config and data

Hermes stores conversation history and agent memory in its data directory (typically ~/.hermes/data). Schedule a daily backup:

# Add to crontab: crontab -e
0 3 * * * tar -czf /var/backups/hermes-$(date +%F).tar.gz ~/.hermes/data ~/.hermes/config.env

Update Hermes

cd ~/.hermes
git pull origin main
source .venv/bin/activate && pip install -r requirements.txt
npm install
sudo systemctl restart hermes

Prefer not to manage it yourself?

AgentOcean deploys a fully managed Hermes instance on a dedicated VPS in about 30 seconds — HTTPS, backups, and monitoring included.

See managed plans Self-host guide

Back to Learn