Hermes Agent Setup Guide: Self-Improving AI Assistant on Your Own Server

I’ve been testing Hermes Agent from Nous Research alongside my OpenClaw setup and OpenFang instance for about a week. The thing that hooked me is the learning loop. Hermes creates skills from tasks it completes, improves those skills during later use, and remembers who you are across sessions. It also migrates your existing OpenClaw config, memories, and skills with a single command.

If you’re comparing self-hosted AI assistant options, our OpenClaw alternatives roundup covers several projects including NanoClaw, nanobot, PicoClaw, ZeroClaw, NullClaw, and OpenFang. For security considerations when running any of these, see the OpenClaw security guide. For the best web UIs and dashboards to manage your Hermes Agent from a browser, see the best Hermes dashboards roundup.

What Hermes Agent actually is

Nous Research built Hermes Agent as what they call a “self-improving” AI assistant. That label actually means something here: the agent watches what it does, extracts reusable skills from complex tasks, and refines those skills the next time it runs them. Most other assistants in this category forget everything between sessions. Hermes carries forward what it learned.

The architecture:

You (CLI / Telegram / Discord / Slack / WhatsApp / Signal / Email)
    ↓
Hermes Gateway (single background process)
    ↓
AI Agent (session store, memory, skills, tools)
    ↓
LLM Provider (OpenRouter, Nous Portal, OpenAI, Anthropic, Ollama, custom)
    ↓
40+ Tools (terminal, web search, browser, file editing, code execution, TTS)

Messages arrive from whatever platform you use. The gateway routes them through a per-chat session store, the agent processes them with access to 40+ built-in tools, and everything runs from a single process. No microservices, no database server.

How it compares to OpenClaw and others

The learning loop is the real differentiator. After you ask Hermes to do something complex (say, deploy a Docker service), it extracts that workflow into a skill. Next time you ask for something similar, it uses and refines that skill. The FTS5 session search means it can recall details from conversations weeks ago. And voice mode in Discord voice channels is something none of the other projects offer.

OpenClaw still has the larger community, more third-party dashboards, and a longer track record. If OpenClaw already works for you, the migration command makes switching painless whenever you’re ready.

Installation

The one-line installer handles Python, Node.js, dependencies, and the hermes command. Works on Linux, macOS, and WSL2.

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

source ~/.bashrc   # or source ~/.zshrc

hermes --version

# Make sure you have Python 3.11+
python3 --version

# Create a virtual environment (recommended)
python3 -m venv ~/.hermes-venv
source ~/.hermes-venv/bin/activate

# Install
pip install hermes-agent

# For voice mode support
pip install hermes-agent[voice]

# For all optional features
pip install hermes-agent[all]

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
git submodule update --init mini-swe-agent

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"
uv pip install -e "./mini-swe-agent"

Installing on a Hetzner VPS

If you want Hermes running 24/7, a cheap VPS does the job. I use a Hetzner CX22 (2 vCPU, 4GB RAM) for €3.99/month.

SSH into your server and run:

ssh root@YOUR_SERVER_IP
apt update && apt upgrade -y
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

Setting up OpenRouter with free models

OpenRouter routes to 200+ models through a single API key. They also have a free tier with several models at zero cost, which is the cheapest way to get started.

Get your API key

1. Go to openrouter.ai and create an account
2. Navigate to Keys in your dashboard
3. Click Create Key and copy the key

Configure Hermes Agent

You can configure interactively or by editing the config files directly.

Interactive setup (recommended):

hermes setup

This walks you through model provider, API key, tools, and platform configuration. When it asks for a provider, select OpenRouter and paste your key.

Manual setup:

Add your API key to ~/.hermes/.env:

echo "OPENROUTER_API_KEY=sk-or-v1-your-key-here" >> ~/.hermes/.env

Set the model in ~/.hermes/config.yaml:

model:
  provider: "openrouter"
  default: "openrouter/free"

The openrouter/free model routes to the best available free model. You can also specify a model directly:

hermes config set model openrouter/free

Switch models on the fly

You don’t need to restart anything to change models. Use the interactive picker:

hermes model

Or switch mid-conversation with a slash command:

/model openrouter/free

Using paid models later

When you’re ready to move beyond free models, just change the model name:

hermes config set model anthropic/claude-sonnet-4.6
# or
hermes config set model openai/gpt-5.4

OpenRouter handles the routing. Your API key stays the same.

First conversation

Start chatting:

hermes

You’ll see a welcome banner showing your model, available tools, and skills. Type a message and press Enter:

❯ What can you help me with?

Some things to try right away:

❯ What's my disk usage? Show the top 5 largest directories.
❯ Search the web for the latest Docker release and summarize it.
❯ Create a Python script that monitors CPU usage and alerts me above 80%.

The agent runs terminal commands, searches the web, reads and edits files, and executes code. No extra configuration needed.

Useful slash commands

Type / to see an autocomplete dropdown. The ones you’ll use most:

Multi-line input and interrupts

Press Alt+Enter or Ctrl+J to add a new line. Useful for pasting code blocks or writing detailed prompts.

If the agent is taking too long, type a new message and press Enter — it interrupts the current task and switches to your new instructions. Ctrl+C also works.

Resume a session

When you exit, Hermes prints a resume command:

hermes --continue    # Resume the most recent session
hermes -c            # Short form

Memory system

Hermes has three layers of memory that work together.

MEMORY.md — Agent’s personal notes

The agent writes its own notes about your environment, conventions, and things it learned. Stored in ~/.hermes/memories/MEMORY.md. Limited to 2,200 characters (~800 tokens) to keep the system prompt bounded.

The agent manages this automatically. When it discovers that your server runs Ubuntu 22.04 with Docker installed, it saves that. When it learns you prefer concise responses, it saves that too. You don’t need to tell it to remember — it watches for useful facts and stores them.

USER.md — Your profile

Information about you: name, preferences, communication style, timezone. Stored in ~/.hermes/memories/USER.md. Limited to 1,375 characters (~500 tokens).

Session search

Beyond the two markdown files, Hermes stores all past conversations in SQLite with FTS5 full-text search. It can search through weeks of old conversations to find something you discussed before:

❯ What did we discuss about the Nginx configuration last week?

The agent searches its session history, summarizes the relevant parts, and gives you the answer. No other assistant in the OpenClaw family does this.

Configure memory

In ~/.hermes/config.yaml:

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375

Skills system

This is the feature I keep coming back to. Skills are not pre-built plugins you install from a hub. The agent creates them from tasks it completes.

How skill creation works

1. You ask Hermes to do something complex (deploy a service, set up a CI pipeline, configure Nginx)
2. Hermes completes the task using its tools
3. After finishing, it extracts the workflow into a reusable skill
4. Next time you ask for something similar, it uses and refines that skill

Skills also self-improve. Each time one runs, the agent checks whether the steps could be better and updates the skill if so.

Browse and install community skills

hermes skills search kubernetes
hermes skills search react --source skills-sh
hermes skills install openai/skills/k8s

Or use the /skills slash command inside chat.

Skills Hub

Community-contributed skills live at agentskills.io. You can browse and install them, or publish your own.

Setting up messaging platforms

Hermes talks to Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, and DingTalk through a single gateway process.

Quick setup

hermes gateway setup

The interactive wizard walks you through each platform. It shows what’s already configured and offers to start the gateway when done.

TELEGRAM_BOT_TOKEN=your-bot-token-here
TELEGRAM_ALLOWED_USERS=your-telegram-user-id

hermes gateway start

DISCORD_BOT_TOKEN=your-bot-token-here
DISCORD_ALLOWED_USERS=your-discord-user-id

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912

hermes gateway start

hermes gateway setup

Run the gateway as a service

On a VPS, you want the gateway running at boot:

# Install as a systemd service
hermes gateway install

# Start it
hermes gateway start

# Check status
hermes gateway status

# View logs
journalctl --user -u hermes-gateway -f

# Enable lingering so it survives logout
sudo loginctl enable-linger $USER

On a headless VPS, use the system service instead:

sudo hermes gateway install --system
sudo hermes gateway start --system

Security

The gateway denies all users by default. Only users in the allowlist can interact:

# In ~/.hermes/.env
TELEGRAM_ALLOWED_USERS=123456789
DISCORD_ALLOWED_USERS=123456789012345678

As an alternative to allowlists, you can use DM pairing. Unknown users get a one-time pairing code when they message the bot:

hermes pairing approve telegram XKGH5N7P
hermes pairing list
hermes pairing revoke telegram 123456789

Terminal backends

By default, Hermes runs commands directly on your machine. For security, you can isolate command execution in a container or send it to a remote server.

# In ~/.hermes/config.yaml
terminal:
  backend: local    # or: docker, ssh, singularity, modal, daytona
  timeout: 180

Docker isolation

terminal:
  backend: docker
  docker_image: python:3.11-slim
  container_cpu: 1
  container_memory: 5120
  container_disk: 51200
  container_persistent: true

Containers run with a read-only root filesystem, all Linux capabilities dropped, no privilege escalation, PID limits, and namespace isolation.

SSH backend

Run commands on a separate machine entirely:

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Voice mode

Hermes has voice support across CLI and messaging. You can talk to it with your mic in the terminal, get spoken replies in Telegram and Discord, and have live voice conversations in Discord voice channels.

Prerequisites

# Install voice dependencies
pip install hermes-agent[voice]

# Optional: free local speech-to-text (recommended)
pip install faster-whisper

# System dependencies (Ubuntu/Debian)
sudo apt install portaudio19-dev ffmpeg libopus0

CLI voice mode

Start the CLI and enable voice:

hermes
/voice on

Press Ctrl+B to record. Speak, and when you stop, it auto-detects silence after 3 seconds and transcribes your audio. If TTS is enabled (/voice tts), the agent speaks its reply back.

Messaging voice replies

In Telegram or Discord, send:

/voice tts

The agent now sends spoken audio alongside text for every response.

Discord voice channels

The agent can join a Discord voice channel, listen to you speak, and reply with spoken audio:

/voice join

This requires additional Discord bot permissions (Connect, Speak, Use Voice Activity) and the Opus codec on your server.

TTS providers

Configure in ~/.hermes/config.yaml:

tts:
  provider: "edge"
  edge:
    voice: "en-US-AriaNeural"

stt:
  provider: "local"
  local:
    model: "base"

Personality and SOUL.md

Hermes uses a file called SOUL.md as its identity. It goes into the system prompt first, before anything else, and shapes how the agent talks and thinks.

Edit it at ~/.hermes/SOUL.md:

# Personality
You are a pragmatic senior engineer with strong taste.
You optimize for truth, clarity, and usefulness over politeness theater.

## Style
- Be direct without being cold
- Prefer substance over filler
- Push back when something is a bad idea
- Keep explanations compact unless depth is useful

## What to avoid
- Sycophancy
- Hype language
- Overexplaining obvious things

Built-in personalities

Switch personalities on the fly with /personality:

/personality concise
/personality pirate

SOUL.md is your baseline. /personality is a session-level overlay.

Scheduled tasks

Hermes has a built-in cron scheduler. Just tell it what you want in plain English:

❯ Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.
❯ Every Friday at 5pm, back up the PostgreSQL database and report the size.
❯ Every hour, check if nginx is running and restart it if not.

The agent creates cron jobs that run through the gateway. Results land on whatever platform you configured.

Migrating from OpenClaw

If you’re coming from OpenClaw, Hermes can import your settings, memories, skills, and API keys.

During first-time setup: The setup wizard (hermes setup) auto-detects ~/.openclaw and offers to migrate.

Anytime after install:

hermes claw migrate              # Interactive migration
hermes claw migrate --dry-run    # Preview what would be migrated
hermes claw migrate --preset user-data   # Migrate without secrets
hermes claw migrate --overwrite  # Overwrite existing conflicts

What gets imported:

• SOUL.md — persona file
• Memories — MEMORY.md and USER.md entries
• Skills — user-created skills go to ~/.hermes/skills/openclaw-imports/
• Command allowlist — approval patterns
• Messaging settings — platform configs, allowed users, working directory
• API keys — Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs tokens
• TTS assets — workspace audio files

How Hermes Agent differs from OpenClaw

I’ve used both extensively. Here are the differences that actually matter day to day:

The learning loop changes how you work with it. In OpenClaw, every complex task starts from scratch. In Hermes, once you’ve walked the agent through deploying a Docker service, it creates a skill for that workflow. Next time you say “deploy the staging API,” it already knows the steps.

Session search gives it long-term recall. OpenClaw’s memory is limited to what fits in its context files. Hermes stores every conversation in SQLite with full-text search. Ask “what port did we configure for Redis last month?” and it finds the answer in old sessions.

The personality system is more structured. OpenClaw uses a system prompt you edit by hand. Hermes has SOUL.md as a durable identity file, session-level /personality overlays, and 14 built-in presets.

Voice mode actually works. Mic input in the CLI, TTS replies on messaging, and live Discord voice channel conversations. Nothing else in the OpenClaw family does this.

Terminal backend isolation. OpenClaw runs commands on your local machine. Hermes can run them in Docker containers, on remote servers via SSH, or in serverless environments like Modal and Daytona. If the agent breaks something, it breaks the sandbox, not your server.

Migration is painless. hermes claw migrate imports everything from OpenClaw — memories, skills, API keys, platform configs. You don’t start over.

Where OpenClaw still wins: bigger community, more third-party dashboards and skins, longer track record. If you want the more battle-tested option, OpenClaw is still it.

CLI command reference

Configuration reference

The full directory structure:

~/.hermes/
├── config.yaml     # Settings (model, terminal, TTS, compression, etc.)
├── .env            # API keys and secrets
├── auth.json       # OAuth provider credentials
├── SOUL.md         # Agent identity
├── memories/       # MEMORY.md, USER.md
├── skills/         # Agent-created skills
├── cron/           # Scheduled jobs
├── sessions/       # Gateway sessions
└── logs/           # Logs (secrets auto-redacted)

Key config options in config.yaml:

model:
  provider: "openrouter"
  default: "openrouter/free"

terminal:
  backend: local
  timeout: 180

memory:
  memory_enabled: true
  user_profile_enabled: true

tts:
  provider: "edge"

stt:
  provider: "local"

display:
  tool_progress: all

If you want an assistant that actually gets better the more you use it, Hermes Agent is the one to try. The skill creation loop and session search are things I haven’t seen in any other project in this space. And if you’re already on OpenClaw, the migration command means you can try it without losing anything.

For other self-hosted assistant options, check out our OpenClaw alternatives roundup. If you want autonomous agents running on schedules, the OpenFang setup guide covers that. For a single Go binary on minimal hardware, see the PicoClaw setup guide. And for the multi-channel web console approach, the CoPaw setup guide has the details. For the best third-party web UIs and dashboards for Hermes Agent, see the best Hermes dashboards roundup.