Hermes Agent Setup Guide (2026): Self-Improving AI on Your Server

I have been testing Hermes Agent from Nous Research alongside my OpenClaw setup and OpenFang instance for months. 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 / TUI / Telegram / Discord / Slack / WhatsApp / Signal / Email / Teams)
    ↓
Hermes Gateway (single process or Docker s6 supervision)
    ↓
AI Agent (session store, memory, skills, MCP, tools)
    ↓
LLM Provider (OpenRouter, Nous Portal, OpenAI, Anthropic, Ollama, custom)
    ↓
40+ Tools + MCP servers (terminal, web search, browser, files, code, 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, WSL2, and native Windows (PowerShell). Prefer Docker Compose if you want a containerized gateway and dashboard on a VPS.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

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

hermes --version

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

mkdir -p ~/.hermes

# First-time setup wizard (writes API keys to ~/.hermes/.env)
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"   # gateway API
      - "9119:9119"   # dashboard (with HERMES_DASHBOARD=1)
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_DASHBOARD=1
      # Match host ownership of ~/.hermes (required on most VPS/NAS mounts)
      - HERMES_UID=${HERMES_UID:-1000}
      - HERMES_GID=${HERMES_GID:-1000}
      # Dashboard auth (required when bound beyond loopback)
      # - HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
      # - HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=change-me
      # Optional OpenAI-compatible API server (do not expose publicly without a key):
      # - API_SERVER_ENABLED=true
      # - API_SERVER_HOST=0.0.0.0
      # - API_SERVER_KEY=${API_SERVER_KEY}
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

export HERMES_UID="$(id -u)"
export HERMES_GID="$(id -g)"
docker compose up -d
docker compose logs -f

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
uv pip install -e ".[all,dev]"

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv ~/.hermes/venvs/hermes-dev --python 3.11
source ~/.hermes/venvs/hermes-dev/bin/activate
uv pip install -e ".[all,dev]"

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://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc

Or skip the bare install and use Docker Compose instead.

Docker Compose deployment

Running Hermes in Docker keeps the install tree immutable under /opt/hermes and stores all user state (config, keys, sessions, skills, memories) in ~/.hermes mounted at /opt/data. You can upgrade by pulling a new image without losing config.

The official repo ships a docker-compose.yml with separate gateway and dashboard services on host networking. The docs also show a single-service layout with bridge networking and published ports. Both work; pick based on how you want to expose the dashboard.

Option A: Single service (bridge networking)

Simple and portable. Good default for most VPS setups.

mkdir -p ~/.hermes

# One-time interactive setup
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Create docker-compose.yml:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"   # gateway OpenAI-compatible API + health
      - "9119:9119"   # web dashboard
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_DASHBOARD=1
      - HERMES_UID=${HERMES_UID:-1000}
      - HERMES_GID=${HERMES_GID:-1000}
      # Required when dashboard binds beyond loopback:
      # - HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
      # - HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=change-me
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

export HERMES_UID="$(id -u)"
export HERMES_GID="$(id -g)"
docker compose up -d

Option B: Official repo compose (host networking)

Matches the upstream docker-compose.yml. Gateway and dashboard share the host network and PID namespace so the dashboard can detect gateway liveness.

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

mkdir -p ~/.hermes
# Run setup once if ~/.hermes is empty
docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup

export HERMES_UID="$(id -u)"
export HERMES_GID="$(id -g)"
docker compose up -d --build

Core of that file (abbreviated):

services:
  gateway:
    build: .
    image: hermes-agent
    container_name: hermes
    restart: unless-stopped
    network_mode: host
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_UID=${HERMES_UID:-10000}
      - HERMES_GID=${HERMES_GID:-10000}
      # Optional API server (needs a key if you bind beyond localhost):
      # - API_SERVER_HOST=0.0.0.0
      # - API_SERVER_KEY=${API_SERVER_KEY}
    command: ["gateway", "run"]

  dashboard:
    image: hermes-agent
    container_name: hermes-dashboard
    restart: unless-stopped
    network_mode: host
    depends_on:
      - gateway
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_UID=${HERMES_UID:-10000}
      - HERMES_GID=${HERMES_GID:-10000}
    # Localhost-only. For remote access: ssh -L 9119:localhost:9119 user@host
    command: ["dashboard", "--host", "127.0.0.1", "--no-open"]

Useful Docker commands

docker compose logs -f                  # Live logs
docker logs --tail 50 hermes            # Recent gateway output
docker exec hermes hermes gateway status
docker exec hermes hermes doctor
docker exec -it hermes hermes           # Interactive CLI against the same data dir
docker compose pull && docker compose up -d   # Upgrade image

Gateway logs are also written under ~/.hermes/logs/gateways/<profile>/current on the host volume, so they survive container restarts.

Docker security notes

• Set HERMES_UID / HERMES_GID (or PUID / PGID) to the host user that owns ~/.hermes so files stay readable after the container drops privileges.
• Never run two gateway containers against the same ~/.hermes directory at once (session and memory files are not multi-writer safe).
• If you enable the OpenAI-compatible API server, set API_SERVER_KEY (min 8 chars) and do not publish it on the public internet without a reverse proxy.
• For browser tools (Playwright), add --shm-size=1g or the Compose equivalent under shm_size: 1gb.

Resource sizing

Browser automation is the memory hog. Without it, 1 GB is fine. With Playwright, plan for at least 2 GB.

Official reference: Hermes Docker docs.

Choosing a model provider

Hermes is provider-agnostic. Secrets go in ~/.hermes/.env; non-secret settings go in ~/.hermes/config.yaml. The interactive picker puts values in the right place:

hermes model

On a fresh install, hermes setup offers three modes:

hermes setup --portal   # Nous Portal + Tool Gateway in one shot
hermes setup            # Interactive: pick Quick / Full / Blank Slate

Common provider choices:

For cheap production models (MiniMax, MiMo, GLM, and friends), see our best cheap models for Hermes Agent guide.

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 without a subscription.

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

Interactive setup (recommended):

hermes setup
# or just:
hermes model

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 set it with:

hermes config set model openrouter/free

Switch models on the fly

hermes model

Or mid-conversation:

/model openrouter/free

Using paid models later

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 (classic CLI or the newer TUI):

hermes          # classic CLI
hermes --tui    # modern TUI (modal overlays, mouse selection)

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. Shift+Enter also works in terminals that support the Kitty keyboard protocol (Kitty, foot, WezTerm, Ghostty; iTerm2 / Alacritty / VS Code with the protocol enabled).

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. On messaging platforms, send /stop or a new message.

Resume a session

hermes --continue    # Resume the most recent session
hermes -c            # Short form
hermes sessions list # List saved sessions

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 browse                      # list hub skills
hermes skills search kubernetes
hermes skills search react --source skills-sh
hermes skills install openai/skills/k8s   # security scan runs first

Installed skills become slash commands automatically (/k8s deploy the staging manifest). Or use /skills inside chat.

Skills Hub

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

MCP servers

Hermes can load Model Context Protocol servers so the agent gains external tools (GitHub, databases, browsers, and more) without custom code.

Add them in ~/.hermes/config.yaml:

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_your_token"

Restart the CLI or gateway after editing. Keep tokens in .env when possible and only put non-secret wiring in config.yaml.

Built-in web dashboard

Hermes ships a web dashboard (default port 9119) for config, sessions, and provider settings. On Docker, enable it with HERMES_DASHBOARD=1 (see Docker Compose). On a bare install:

hermes dashboard
# or bind loopback only for remote SSH tunnels:
hermes dashboard --host 127.0.0.1 --no-open

Always put auth in front of a non-loopback bind. For a deeper walkthrough of the built-in UI and third-party options, see the Hermes dashboard guide and best Hermes dashboards.

Setting up messaging platforms

Hermes talks to Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Microsoft Teams, 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

# From the Hermes install tree (curl installer layout)
cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"   # includes faster-whisper for local STT

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

On native Windows, the install tree is under %LOCALAPPDATA%\hermes\hermes-agent.

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
• Workspace instructions — AGENTS.md (with --workspace-target)

Troubleshooting

When something feels off, run this sequence before adding more features:

hermes doctor           # Config / env / dependency checks
hermes model            # Re-select provider and model
hermes setup            # Re-run wizard if needed
hermes sessions list    # Confirm sessions and profile
hermes --continue       # Resume last chat
hermes gateway status   # Messaging gateway health

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, MCP, compression, etc.)
├── .env            # API keys and secrets
├── auth.json       # OAuth provider credentials
├── SOUL.md         # Agent identity
├── memories/       # MEMORY.md, USER.md
├── skills/         # Agent-created and hub skills
├── cron/           # Scheduled jobs
├── sessions/       # Conversation history
├── profiles/       # Multi-profile gateways (optional)
└── 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, session search, Docker deployment path, and built-in dashboard make it a solid 24/7 option on a cheap VPS. 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 built-in UI and third-party web UIs, see the Hermes dashboard guide and best Hermes dashboards roundup. For affordable model recommendations including MiniMax M3, MiMo V2.5 Pro, and GLM 5.2, see the best cheap models for Hermes Agent guide. If you are looking for a minimal coding agent to pair with Hermes, our Pi coding agent setup guide covers installation, model configuration, and the best extensions. For structured task management with multi-agent workflows, the Hermes Kanban setup guide covers task boards, dependencies, and coordination patterns. Catalog of related GitHub projects (OpenClaw, Pi, OpenCode, memory, gateways): top AI GitHub repos.