Hermes Agent is one of those projects that moves fast. Since its February 2026 launch, Nous Research has shipped nine releases in seven weeks. v0.9.0 landed on April 13 and it is a different beast: a local web dashboard for managing settings and sessions from your browser, 16 messaging platforms (including iMessage and WeChat), native Android/Termux support, built-in backup and import commands, a fast mode for low-latency inference, and a pluggable context engine. The project went from "interesting experiment" to "production-grade personal agent" in under two 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 those 16 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

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 16 messaging gateways: Telegram, Discord, Slack, WhatsApp, Signal, Matrix, iMessage, WeChat, WeCom, Email, SMS, DingTalk, Feishu, Mattermost, Home Assistant, and Webhooks.

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.

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 or use 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

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.

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.9.0 (2026.4.13)
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 portal with 400+ models. If you want to stay in the Nous ecosystem:

hermes config set model.provider nous

The hermes model command walks you through authentication.

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

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 model`	Per-token (see pricing)	400+ models, native integration
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 asks before running potentially dangerous commands. On a server, keep this enabled:

hermes config set approval_mode ask

The three modes:

ask: Prompts you before any command that modifies files, installs packages, or touches the network. Use this. Since v0.8.0, Telegram and Slack show native approval buttons instead of requiring you to type a response.
smart: An AI model assesses risk and only prompts for genuinely dangerous commands. Faster, but relies on the AI's judgment.
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 16 platforms. Beyond Telegram: Discord, Slack, WhatsApp, Signal, Matrix, iMessage (via BlueBubbles), WeChat, WeCom, Email, SMS, DingTalk, Feishu/Lark, Mattermost, Home Assistant, 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, and path traversal prevention, shell injection neutralization, and Twilio webhook validation in v0.9.0. 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