Updated August 2026 for Hermes Agent v0.20.

Hermes Agent is one of those projects that moves fast. Since its February 2026 launch, Nous Research has kept up a near-weekly release rhythm; v0.20.4 landed on August 18, 2026. The two months since v0.18 alone brought real-time conversational voice with on-device wake words, agent-to-agent communication (A2A v1.0), signed outbound webhooks so the agent can push events to your systems, grounded research with verifiable citations, Bot Mode (a roster of named bots, each with its own memory, skills, and model), and a desktop app that grew artifacts and a plugin SDK. The project went from "interesting experiment" to "production-grade personal agent" in a few months.

Running it on your laptop works for quick experiments. But an agent that sleeps when you close your lid, that you can only reach from your keyboard, and that forgets its workspace on reboot is not very useful long-term. A VPS fixes all three: the agent stays online 24/7, you reach it from any of its 24+ supported messaging platforms on your phone, and its memories and skills persist across sessions.

The setup is straightforward. Spin up a VM, create a non-root user for isolation, install Hermes, pick your model and gateway, and wrap the whole thing in a systemd service. That is the entire procedure.

Self-hosting AI agents on a VPS

Coming from OpenClaw? See our honest Hermes Agent vs OpenClaw comparison.

Why self-host now? The vendor lock-in lesson

On April 4, 2026, Anthropic cut off third-party AI agents from Claude Pro and Max subscriptions. Until that day, tools like OpenClaw let you run heavy agentic workloads on a flat monthly fee. Overnight, those users got a 400 error and a migration notice. The only options left: switch to per-token API billing (potentially 10x the cost for power users), buy enterprise usage bundles, or move to Anthropic's own Claude Code Channels, a first-party competitor to OpenClaw that launched the same month.

The pattern is clear. Build your workflow on a single provider's platform, and one policy change can break everything. Self-hosted agents like Hermes avoid that trap entirely. Hermes is provider-agnostic: it supports 15+ inference backends out of the box, from OpenRouter to Nous Portal to a local Ollama server. If a provider changes its terms or pricing, you swap it with one command and keep working. Your memories, skills, and sessions stay on your server regardless of which LLM sits behind them.

What is Hermes Agent and why self-host it?

Hermes Agent is an open-source (MIT license) AI agent built by Nous Research. It connects to LLM providers, executes terminal commands, browses the web, and remembers what it learns across sessions. It builds reusable skills from tasks it completes and supports 24+ messaging gateways: Telegram, Discord, Slack, WhatsApp, Signal, Matrix, iMessage (via BlueBubbles), Microsoft Teams, Google Chat, LINE, WeChat, WeCom, QQ Bot, Email, SMS, DingTalk, Feishu, Mattermost, Home Assistant, ntfy, SimpleX, Open WebUI, Webhooks, and more.

Self-hosting means your prompts and data stay on your server. No third-party agent platform sees your conversations. The agent runs continuously, builds context over time, and costs only VPS hosting plus the LLM API calls you make.

Hermes Cloud or your own VPS?

Since July 2026 there is an official hosted option: Hermes Cloud, part of Nous Portal. You pick a model and a server size, the instance is live in about a minute, it scales down when idle, and it bills from the same Portal credit balance that pays for models and tools. For a first contact with Hermes, or for handing an agent to a non-technical teammate, it is the shortest path.

This guide still exists because a hosted agent trades away the things that make self-hosting attractive in the first place:

Your data stays yours. On a VPS, prompts, memories, learned skills, and API keys sit on a disk you control. A hosted instance keeps all of that, plus your model spend, inside one vendor's account.
Provider freedom. Hermes Cloud runs on Portal credits. A self-hosted agent talks to any backend: OpenRouter, Anthropic, a local Ollama server, or Nous Portal itself if that is what you prefer. The vendor lock-in lesson above applies to agent hosting exactly as it applies to models.
A full server, not just an agent. Your VPS also runs the cron jobs, databases, and reverse proxies the agent works on. The agent lives next to real workloads instead of alone in a sandbox, and the same machine can host anything else you need.
Hardware limits instead of plan limits. Hosted sizes cap concurrent sessions per tier. On your own server, the ceiling is the RAM and CPU you rented, and upgrading is a resize, not a plan change.

Nothing here locks you in either direction: Hermes stores its entire state in one directory, and the built-in backup and import commands move an agent between servers in minutes. The rest of this guide covers the VPS path.

What does Hermes Agent need to run on a VPS?

A Linux server with Git installed. That is the only prerequisite. The installer pulls in Python 3.11+, Node.js v22, ripgrep, and ffmpeg automatically. For hardware: 2 GB of RAM and 10 GB of disk is the minimum. 4 GB RAM is better if you plan to run multiple gateway sessions, several Bot Mode bots, or the web dashboard alongside the agent.

Requirement	Minimum	Recommended
OS	Ubuntu 22.04 / Debian 12	Ubuntu 24.04
RAM	2 GB	4 GB+
Disk	10 GB free	20 GB+
CPU	1 vCPU	2+ vCPU

For a plan-by-plan breakdown of what each workload needs, see the Hermes Agent VPS sizing guide.

Prerequisites

Before installing Hermes Agent, set up a non-root user and a basic firewall. If you already have a secured VPS, skip to the installation section.

Create a dedicated user

SSH into your server as root and create a user for Hermes:

adduser hermes --disabled-password --gecos ""
usermod -aG sudo hermes

Give this user passwordless sudo (needed for service management):

echo "hermes ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/hermes
chmod 440 /etc/sudoers.d/hermes

Copy your SSH key so you can log in as this user:

mkdir -p /home/hermes/.ssh
cp ~/.ssh/authorized_keys /home/hermes/.ssh/
chown -R hermes:hermes /home/hermes/.ssh
chmod 700 /home/hermes/.ssh
chmod 600 /home/hermes/.ssh/authorized_keys

From now on, work as the hermes user:

su - hermes

Configure the firewall

Install UFW and allow only SSH:

sudo apt-get install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw --force enable

Check the active rules:

sudo ufw status verbose

The output should show SSH allowed and all other incoming traffic denied. The Hermes gateway makes outbound connections to Telegram's API, so no inbound ports need to be opened for messaging.

How do I install Hermes Agent on Ubuntu?

One command. Run it as the hermes user, not root.

One-click install

Virtua.Cloud maintains a turnkey install script that sets up Hermes Agent with systemd persistence in one shot:

curl -fsSL https://virtua.sh/i/hermes-ssh | bash

The script handles everything covered in the sections below: installing Hermes and creating the systemd service. After it finishes, skip ahead to configuring your LLM provider.

Prefer containers? The same setup runs in Docker: see Run Hermes Agent with Docker Compose on a VPS.

Manual install

If you prefer to install step by step, download the upstream installer and review it before running:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o /tmp/hermes-install.sh
less /tmp/hermes-install.sh

The script installs Python 3.11+ via uv, Node.js v22, ripgrep, ffmpeg, and the hermes CLI. When you are satisfied:

bash /tmp/hermes-install.sh

Reload your shell to pick up the new hermes command:

source ~/.bashrc

Check the installed version:

hermes --version

Expected output:

Hermes Agent v0.20.4 (2026.8.18)
Project: /home/hermes/.hermes/hermes-agent
Python: 3.11.15
...

Run the diagnostic tool to check for missing dependencies:

hermes doctor

Look for green checkmarks. Warnings about unconfigured API keys are expected at this stage. Red items about Python or Git need fixing before you continue.

How do I configure the LLM provider?

Hermes Agent does not include a model. You connect it to a provider API and pay per token. The fastest way to set everything up is the setup wizard:

hermes setup

This walks you through choosing a provider, entering your API key, enabling tools, and configuring your gateway in one interactive session. If you prefer to configure each piece manually, read on. You can also switch providers at any time with hermes model.

Option 1: OpenRouter (recommended for getting started)

Create an account at openrouter.ai and generate an API key.

The installer created ~/.hermes/.env with a full template. Lock down its permissions first:

chmod 600 ~/.hermes/.env

Open the file and set your API key on the OPENROUTER_API_KEY= line:

nano ~/.hermes/.env

Find the line OPENROUTER_API_KEY= and add your key after the = sign. Save and exit (Ctrl+X, then Y, then Enter).

Set the default model:

hermes config set model.provider openrouter
hermes config set model.default anthropic/claude-sonnet-4

Confirm the file is not readable by other users:

ls -la ~/.hermes/.env

The permissions should show -rw------- (600). Only the hermes user can read this file.

Option 2: Nous Portal

Nous Research runs their own inference platform with 300+ models plus a Tool Gateway that covers web search, image generation, text-to-speech, and a cloud browser under one subscription. One command wires all of it:

hermes setup --portal

This logs you in via OAuth, sets Nous as your provider, and enables the Tool Gateway. Check what is connected at any time with hermes portal info. You can still bring your own keys per tool; the gateway is per-backend, not all-or-nothing.

Option 3: Custom OpenAI-compatible endpoint

If you run your own inference server (Ollama, vLLM, llama.cpp) or use another provider:

echo 'OPENAI_BASE_URL=http://localhost:11434/v1' >> ~/.hermes/.env
echo 'OPENAI_API_KEY=ollama' >> ~/.hermes/.env
echo 'LLM_MODEL=llama3.1:70b' >> ~/.hermes/.env

Running the model on the same server is its own topic (GPU sizing, quantization, hybrid setups): see Hermes Agent with Ollama: a fully local AI agent.

LLM provider comparison

Provider	Env Variable	Pricing Model	Notes
OpenRouter	`OPENROUTER_API_KEY`	Per-token, varies by model (see pricing)	200+ models, single key
Nous Portal	via `hermes setup --portal`	Per-token (see pricing)	300+ models, Tool Gateway included
Anthropic	`ANTHROPIC_API_KEY`	Per-token (see pricing)	Direct Claude access
Google AI Studio	`GOOGLE_API_KEY`	Per-token (see pricing)	Gemini models, native since v0.8.0
xAI (Grok)	`XAI_API_KEY`	Per-token (see pricing)	Grok models, native since v0.9.0
Hugging Face	`HF_TOKEN`	Per-token (see pricing)	Full model suite
Ollama (local)	`OPENAI_BASE_URL` + `OPENAI_API_KEY`	Free (self-hosted)	Needs GPU VPS for good speed
vLLM	`OPENAI_BASE_URL` + `OPENAI_API_KEY`	Free (self-hosted)	GPU required

Provider failover is built in since v0.6.0. You can set an ordered chain of providers so if one goes down, the agent automatically falls back to the next.

Test that the LLM connection works:

hermes -m "What is 2+2? Reply with just the number."

If you get a response, the provider is configured. If you see an authentication error, double-check your API key in ~/.hermes/.env.

How do I configure approval mode?

Hermes Agent has a built-in approval system that reviews potentially dangerous commands before they run. Since v0.19, new installs default to smart mode, where an LLM reviewer assesses each flagged command on its own. On a server that can execute anything, we prefer explicit confirmation:

hermes config set approval_mode ask

The three modes:

ask: Prompts you before any command that modifies files, installs packages, or touches the network. Telegram and Slack show native approval buttons instead of requiring you to type a response. The safest choice for a fresh setup.
smart: An AI model assesses risk and only prompts for genuinely dangerous commands. The default since v0.19. Pair it with user-defined deny rules, which block matching commands no matter what the reviewer decides.
off: No checks. Every command runs immediately. Do not use this on a server.

How do I connect Hermes Agent to Telegram?

The messaging gateway lets you chat with Hermes from your phone. Telegram is the most common setup. The gateway makes outbound connections to Telegram's API, so no inbound ports need opening.

Step 1: Create a Telegram bot

Open Telegram and message @BotFather. Send these commands:

/newbot
Enter a name for your bot (e.g., "My Hermes Agent")
Enter a username (must end in bot, e.g., myhermes_agent_bot)

BotFather replies with a bot token. It looks like 7123456789:AAHx.... Copy it.

Step 2: Get your Telegram user ID

Message @userinfobot on Telegram. It replies with your numeric user ID. Copy this number.

Step 3: Configure the gateway

Add the bot token and your user ID to the environment file:

echo 'TELEGRAM_BOT_TOKEN=7123456789:AAHxYourTokenHere' >> ~/.hermes/.env
echo 'TELEGRAM_ALLOWED_USERS=your_numeric_user_id' >> ~/.hermes/.env

The TELEGRAM_ALLOWED_USERS variable is a security control. Only the user IDs listed here can interact with your bot. Without it, anyone who finds your bot can send it commands. Separate multiple IDs with commas.

Step 4: Test the gateway

Start the gateway in the foreground:

hermes gateway

Send a message to your bot in Telegram. Your message appears in the terminal and a response comes back. Press Ctrl+C to stop once you have confirmed it works.

If the bot does not respond, check:

The bot token is correct in ~/.hermes/.env
Your user ID is in TELEGRAM_ALLOWED_USERS
The VPS can reach api.telegram.org on port 443 (outbound HTTPS)

Hermes now supports 24+ platforms. Beyond Telegram: Discord, Slack, WhatsApp, Signal, Matrix, iMessage (via BlueBubbles), Microsoft Teams, Google Chat, LINE, WeChat, WeCom, QQ Bot, Email, SMS, DingTalk, Feishu/Lark, Mattermost, Home Assistant, ntfy, SimpleX, Open WebUI, and Webhooks. Run hermes gateway setup for an interactive wizard that configures any of them.

How do I run Hermes Agent as a systemd service?

Running hermes gateway in a terminal session means it stops when you disconnect. A systemd user service keeps the gateway running after logout and restarts it automatically if it crashes or the server reboots.

Install the service

Hermes provides a built-in command:

hermes gateway install

This creates a service file at ~/.config/systemd/user/hermes-gateway.service and enables lingering automatically. Lingering keeps user services running after you log out of SSH.

Start the service and enable it for boot:

systemctl --user enable --now hermes-gateway

Check the service status:

systemctl --user status hermes-gateway

Look for Active: active (running) in the output. If it says failed, check the logs.

Check the logs

View live gateway logs:

journalctl --user -u hermes-gateway -f

Press Ctrl+C to stop following. The gateway logs show every incoming message, LLM call, and tool execution.

Set the working directory

By default, the gateway uses the home directory as its workspace. Set a dedicated project directory:

echo 'MESSAGING_CWD=/home/hermes/projects' >> ~/.hermes/.env
mkdir -p /home/hermes/projects

Restart the service to apply:

systemctl --user restart hermes-gateway

Manage from your browser

Since v0.9.0, Hermes ships a local web dashboard. Once the gateway is running, open it with:

hermes dashboard

This launches a browser-based UI where you can manage settings, browse sessions and skills, and configure gateways without touching the terminal. On a VPS, you can tunnel the dashboard port over SSH to access it from your local machine.

How do I back up Hermes Agent data?

Hermes stores all its state in ~/.hermes/: memories, learned skills, session history, configuration, cron jobs, and your agent persona. Losing it means the agent forgets everything.

Since v0.9.0, Hermes has built-in backup and restore commands:

hermes backup

This creates a timestamped snapshot of your entire ~/.hermes/ directory. To restore on the same server or migrate to a new one:

hermes import /path/to/backup.tar.gz

For automated daily backups, schedule it with cron:

(crontab -l 2>/dev/null; echo "0 3 * * * /home/hermes/.local/bin/hermes backup") | crontab -

For off-server backups, rsync the backup directory to another machine or object storage. Keeping backups only on the same VPS does not protect against disk failure.

How do I update Hermes Agent?

Hermes Agent includes a built-in update command. Back up first, then update:

hermes backup
hermes update

Check the new version:

hermes --version

Check for any configuration changes needed after the update:

hermes config migrate
hermes doctor

config migrate adds new configuration options with their defaults. hermes doctor checks that everything still works.

Restart the gateway service to run the new version:

systemctl --user restart hermes-gateway
systemctl --user status hermes-gateway

If something breaks after an update, restore from backup:

systemctl --user stop hermes-gateway
hermes import /path/to/backup.tar.gz
systemctl --user start hermes-gateway

Security hardening checklist

A VPS-hosted AI agent that executes terminal commands needs attention to security. Here is a summary of what this guide configured and a few additional steps.

Already configured in this guide:

Non-root user (hermes) with dedicated home directory
UFW firewall denying all inbound traffic except SSH
API keys in ~/.hermes/.env with 600 permissions
TELEGRAM_ALLOWED_USERS restricting bot access to your user ID
approval_mode: ask requiring confirmation for dangerous commands

Additional hardening:

Review the agent's learned skills periodically:

ls -la ~/.hermes/skills/

Skills are scripts the agent writes and reuses. Audit them like you would any code running on your server.

Monitor gateway logs for unexpected users or unusual activity:

journalctl --user -u hermes-gateway --since "1 hour ago" --no-pager

Hermes has hardened its security posture with each release: secret exfiltration blocking since v0.7.0, MCP OAuth 2.1 with PKCE and SSRF protections in v0.8.0, path traversal prevention, shell injection neutralization, and Twilio webhook validation in v0.9.0, user-defined deny rules that hold even with approvals off in v0.19, and license plus security scanning on skill installs in v0.20.4. Keep your install up to date to benefit from these protections.

Troubleshooting

Since v0.9.0, you can run /debug in any chat session or hermes debug share from the terminal to generate a diagnostic report. This is the fastest way to identify issues.

The gateway fails to start:

journalctl --user -u hermes-gateway -n 50 --no-pager

Common causes: invalid bot token, missing API key, or network issues.

Telegram bot does not respond:

Check the bot token and allowed users:

grep TELEGRAM ~/.hermes/.env

Test outbound connectivity:

curl -s https://api.telegram.org/bot<YOUR_TOKEN>/getMe

A valid response with your bot's info confirms the token and network are working.

hermes command not found after install:

source ~/.bashrc

If still missing, check if ~/.local/bin is in your PATH:

echo $PATH | tr ':' '\n' | grep local

High memory usage:

Check what is consuming resources:

top -bn1 | head -20

If the agent spawns long-running processes, lower the workload or upgrade your VPS.

What does it cost?

Self-hosting Hermes Agent on a VPS costs the server plus LLM API usage. The two cost components are:

VPS hosting: A VPS with 2+ vCPU and 4 GB RAM. Check Virtua.Cloud VPS plans for current pricing.
LLM API calls: All supported providers use per-token pricing. Your monthly cost depends on which model you choose and how often you use the agent. Check your provider's pricing page for current rates.

The real savings are not just financial. You own your agent's data, pick any provider you want, and no policy change can shut you down overnight.

Run Claude Code on a VPS