---
title: "Hermes Agent Setup Guide (2026): Self-Improving AI on Your Server"
description: "Install Hermes Agent v0.18 on Linux with free models from OpenRouter. Covers Docker Compose, Telegram, Discord, Slack, WhatsApp, and the built-in web dashboard. Updated July 2026."
date: 2026-07-14
categories: ["ai"]
tags: ["ai-tools","self-hosted","vps"]
---

import YouTubeEmbed from "@components/widgets/YouTubeEmbed.astro";
import Button from "@components/widgets/Button.astro";
import Notice from "@components/widgets/Notice.astro";
import ListCheck from "@components/widgets/ListCheck.astro";
import Accordion from "@components/widgets/Accordion.astro";
import Tabs from "@components/widgets/Tabs.astro";
import Tab from "@components/widgets/Tab.astro";

I have been testing [Hermes Agent](https://github.com/NousResearch/hermes-agent) from Nous Research alongside my [OpenClaw setup](/clawdbot-setup-guide/) and [OpenFang instance](/openfang-setup-guide/) 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.

<Button text="Hermes Agent GitHub" link="https://github.com/NousResearch/hermes-agent" variant="solid" color="blue" size="md" icon="github" />

<Notice type="info" title="What this guide covers">
<ListCheck>
<ul>
<li>Installing Hermes Agent on a Linux VPS via the one-line installer</li>
<li>Running Hermes with Docker Compose (gateway + dashboard)</li>
<li>Choosing providers (Nous Portal, OpenRouter free tier, local models)</li>
<li>Setting up Telegram, Discord, Slack, WhatsApp, Signal, Teams, and Matrix</li>
<li>Memory, skills, MCP servers, and the built-in web dashboard</li>
<li>Voice mode for CLI and messaging platforms</li>
<li>Scheduled tasks with natural-language cron jobs</li>
<li>Troubleshooting and how Hermes differs from OpenClaw, nanobot, and OpenFang</li>
</ul>
</ListCheck>
</Notice>

If you're comparing self-hosted AI assistant options, our [OpenClaw alternatives](/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](/openclaw-security-guide/). For the best web UIs and dashboards to manage your Hermes Agent from a browser, see the [best Hermes dashboards](/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

| Feature | Hermes Agent | OpenClaw | nanobot | OpenFang |
|---|---|---|---|---|
| **Built by** | Nous Research | Community | HKUDS | RightNow AI |
| **Language** | Python | TypeScript | Python | Rust |
| **Install** | `curl` / Docker / Desktop | `curl` one-liner | pip | `curl` one-liner |
| **Learning loop** | Yes (skill creation + improvement) | No | No | No |
| **Channels** | 12+ (Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Teams, Home Assistant, Mattermost, Matrix, DingTalk, CLI) | Telegram, WhatsApp, Slack, Discord | Telegram, Discord, WhatsApp, Slack, Feishu, DingTalk, Email, QQ | 40 adapters |
| **Memory** | MEMORY.md + USER.md + FTS5 session search + Honcho user modeling | File-based + semantic search | Built-in | SQLite + vector |
| **Skills** | Auto-created from experience, self-improving, Skills Hub | Community skills | Built-in | Agent templates |
| **Voice mode** | CLI mic + messaging TTS + Discord voice channels | No | No | No |
| **Terminal backends** | Local, Docker, SSH, Daytona, Singularity, Modal | Local | Local | Local, Docker |
| **Scheduled tasks** | Natural-language cron with platform delivery | Cron | Cron | Cron + autonomous Hands |
| **OpenClaw migration** | Built-in (`hermes claw migrate`) | N/A | No | No |
| **Personality system** | SOUL.md + 14 built-in presets + custom | System prompt | System prompt | System prompt |
| **License** | MIT | MIT | MIT | MIT |

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.

<Tabs>
<Tab name="One-line install">

The recommended approach for bare-metal or VPS installs.

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

After it finishes, reload your shell:

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

Verify the install:

```bash
hermes --version
```

On native Windows (PowerShell):

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

</Tab>
<Tab name="Docker Compose">

Best for a 24/7 VPS. The official image mounts `~/.hermes` at `/opt/data` and runs the gateway under s6 supervision.

```bash
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
```

Then create a `docker-compose.yml` (or clone the [repo file](https://github.com/NousResearch/hermes-agent/blob/main/docker-compose.yml)):

```yaml
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"
```

Start it:

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

Open the dashboard at `http://127.0.0.1:9119` (use an SSH tunnel for remote access: `ssh -L 9119:localhost:9119 user@your-server`).

Full Docker details are in the [Docker Compose section](#docker-compose-deployment) below.

</Tab>
<Tab name="From source">

For contributors or if you want the latest development version:

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

Manual clone fallback (keep the venv outside the source tree so the agent cannot wipe its own runtime):

```bash
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]"
```

</Tab>
</Tabs>

### Installing on a Hetzner VPS

If you want Hermes running 24/7, a cheap VPS does the job. I use a [Hetzner CX22](https://www.bitdoze.com/hetzner-cloud-review/) (2 vCPU, 4GB RAM) for €3.99/month.

<Notice type="success" title="Get Started with Hetzner">
[Get €20 credit](https://go.bitdoze.com/hetzner), [Hostinger VPS](https://go.bitdoze.com/hostinger-vps) when you sign up through our referral link. That covers about 5 months of running Hermes Agent.
</Notice>

SSH into your server and run:

```bash
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](#docker-compose-deployment) 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`](https://github.com/NousResearch/hermes-agent/blob/main/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.

```bash
mkdir -p ~/.hermes

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

Create `docker-compose.yml`:

```yaml
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"
```

```bash
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](https://github.com/NousResearch/hermes-agent/blob/main/docker-compose.yml). Gateway and dashboard share the host network and PID namespace so the dashboard can detect gateway liveness.

```bash
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):

```yaml
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

```bash
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

<Notice type="warning" title="Do not expose the dashboard unauthenticated">
The built-in dashboard stores API keys. Keep it on `127.0.0.1` and use an SSH tunnel, or put it behind auth (basic auth env vars, OAuth, or a reverse proxy). `HERMES_DASHBOARD_INSECURE` is a deprecated no-op; non-loopback binds require a real auth provider.
</Notice>

- 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

| Resource | Minimum | Recommended |
|---|---|---|
| Memory | 1 GB | 2–4 GB |
| CPU | 1 core | 2 cores |
| Disk (data volume) | 500 MB | 2+ GB (grows with sessions/skills) |

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](https://hermes-agent.nousresearch.com/docs/user-guide/docker).

## 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:

```bash
hermes model
```

On a fresh install, `hermes setup` offers three modes:

| Mode | Best for |
|---|---|
| **Quick Setup (Nous Portal)** | Fastest path: OAuth login, 300+ models, Tool Gateway (web search, image gen, TTS, cloud browser) under one subscription |
| **Full Setup** | Bring your own keys (OpenRouter, Anthropic, OpenAI, etc.) and walk every option |
| **Blank Slate** | Minimal agent (file ops + terminal only); opt in to tools later |

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

<Notice type="info" title="Minimum context: 64K tokens">
Hermes needs a model with at least **64,000 tokens** of context for multi-step tool calling. Most hosted models meet this. For local models (Ollama, llama.cpp), set context to at least 64K (for example `-c 65536` or `--ctx-size 65536`).
</Notice>

Common provider choices:

| Provider | Setup | Notes |
|---|---|---|
| **Nous Portal** | `hermes setup --portal` | One sub for models + tools |
| **OpenRouter** | API key + `openrouter/free` or paid model | Free tier available; see below |
| **Anthropic / OpenAI** | API key or OAuth via `hermes model` | Direct vendor access |
| **Ollama / vLLM / custom** | Custom endpoint base URL + model name | Fully local or self-hosted |
| **MiniMax, DeepSeek, xAI, Gemini, etc.** | Configure with `hermes model` | Large catalog; see [providers docs](https://hermes-agent.nousresearch.com/docs/integrations/providers) |

For cheap production models (MiniMax, MiMo, GLM, and friends), see our [best cheap models for Hermes Agent](/best-cheap-models-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](https://openrouter.ai/openrouter/free) 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](https://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):**

```bash
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`:

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

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

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

The `openrouter/free` model routes to the best available free model. You can also set it with:

```bash
hermes config set model openrouter/free
```

### Switch models on the fly

```bash
hermes model
```

Or mid-conversation:

```
/model openrouter/free
```

### Using paid models later

```bash
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):

```bash
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:

| Command | What it does |
|---|---|
| `/help` | Show all available commands |
| `/model` | Switch models interactively |
| `/tools` | List available tools |
| `/personality pirate` | Try a fun personality |
| `/new` or `/reset` | Start a fresh conversation |
| `/save` | Save the conversation |
| `/compress` | Compress context when it gets long |
| `/usage` | Show token usage for this session |
| `/skills` | Browse installed skills |
| `/retry` / `/undo` | Retry or undo the last turn |
| `/voice on` | Enable voice mode |

### 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

```bash
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`:

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

<Notice type="info" title="Upgrade to vector-based memory">
Hermes can use [Hindsight](/hindsight-docker-deploy/) as its memory backend instead of the built-in MEMORY.md and session search. Hindsight stores memories as vector embeddings with entity extraction, which means better recall for complex queries and cross-session learning. See the [Hindsight integration](https://hindsight.vectorize.io/integrations) for setup details.
</Notice>

## 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

```bash
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](https://agentskills.io). You can browse and install them, or publish your own.

## MCP servers

Hermes can load [Model Context Protocol](https://modelcontextprotocol.io/) servers so the agent gains external tools (GitHub, databases, browsers, and more) without custom code.

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

```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](#docker-compose-deployment)). On a bare install:

```bash
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](/hermes-dashboard-guide/) and [best Hermes dashboards](/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

```bash
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.

<Tabs>
<Tab name="Telegram">

1. Talk to [@BotFather](https://t.me/BotFather) on Telegram and create a new bot
2. Copy the bot token
3. Add it to `~/.hermes/.env`:

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

To find your user ID, talk to [@userinfobot](https://t.me/userinfobot) on Telegram.

4. Start the gateway:

```bash
hermes gateway start
```

</Tab>
<Tab name="Discord">

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
2. Create a new application and add a Bot
3. Under **Privileged Gateway Intents**, enable Message Content Intent
4. Copy the bot token and add it to `~/.hermes/.env`:

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

5. Invite the bot to your server with this URL (replace `YOUR_APP_ID`):

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

6. Start the gateway:

```bash
hermes gateway start
```

</Tab>
<Tab name="WhatsApp / Signal">

WhatsApp and Signal both work through the gateway. Run the setup wizard:

```bash
hermes gateway setup
```

Select the platform you want and follow the prompts. WhatsApp uses the Baileys library for web client pairing. Signal requires the Signal CLI.

</Tab>
</Tabs>

### Run the gateway as a service

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

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
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.

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

| Backend | What it does | Best for |
|---|---|---|
| `local` | Runs on your machine (default) | Development, trusted tasks |
| `docker` | Isolated containers | Security, reproducibility |
| `ssh` | Remote server | Keeping the agent away from its own code |
| `daytona` | Cloud sandbox workspace | Persistent remote dev environments |
| `singularity` | HPC containers | Cluster computing |
| `modal` | Serverless cloud | Scale-to-zero, pay-per-use |

### Docker isolation

```yaml
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:

```yaml
terminal:
  backend: ssh
```

```bash
# 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

```bash
# 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:

```bash
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

| Provider | Cost | Quality | Setup |
|---|---|---|---|
| Edge TTS | Free | Good | Works out of the box |
| NeuTTS | Free | Good | `uv pip install "neutts[all]"` in the Hermes venv |
| ElevenLabs | Paid | Premium | Set `ELEVENLABS_API_KEY` |
| OpenAI TTS | Paid | Good | Set `VOICE_TOOLS_OPENAI_KEY` |

Configure in `~/.hermes/config.yaml`:

```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`:

```markdown
# 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`:

| Name | Description |
|---|---|
| `helpful` | Friendly, general-purpose assistant |
| `concise` | Brief, to-the-point responses |
| `technical` | Detailed technical expert |
| `creative` | Innovative thinking |
| `teacher` | Patient educator with examples |
| `pirate` | Tech-savvy buccaneer |
| `noir` | Hard-boiled detective narration |

```
/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:**

```bash
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:

```bash
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
```

| Symptom | Likely cause | Fix |
|---|---|---|
| Empty or broken replies | Wrong provider auth or model | `hermes model` and re-auth |
| Custom endpoint returns garbage | Bad base URL / model name | Test the endpoint outside Hermes first |
| Gateway up but no messages | Token, allowlist, or platform setup | `hermes gateway setup` + `hermes gateway status` |
| `--continue` finds nothing | Different profile or unsaved session | `hermes sessions list` |
| Docker permission errors on `~/.hermes` | UID/GID mismatch | Set `HERMES_UID` / `HERMES_GID` to host owner |
| Dashboard fails on public bind | Auth required | Basic auth env vars, OAuth, or bind `127.0.0.1` |

## 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

| Command | Description |
|---|---|
| `hermes` | Start chatting (classic CLI) |
| `hermes --tui` | Start the modern TUI |
| `hermes model` | Choose your LLM provider and model |
| `hermes tools` | Configure which tools are enabled |
| `hermes setup` | Full setup wizard |
| `hermes setup --portal` | Quick Nous Portal + Tool Gateway setup |
| `hermes config set KEY VAL` | Set a config value |
| `hermes config edit` | Open config.yaml in your editor |
| `hermes gateway setup` | Configure messaging platforms |
| `hermes gateway install` | Install as a system service |
| `hermes gateway start` | Start the messaging gateway |
| `hermes gateway status` | Check gateway status |
| `hermes dashboard` | Start the built-in web dashboard |
| `hermes skills browse` | Browse the Skills Hub |
| `hermes skills search QUERY` | Search for skills |
| `hermes skills install SKILL` | Install a skill |
| `hermes claw migrate` | Migrate from OpenClaw |
| `hermes sessions list` | List saved sessions |
| `hermes update` | Update to latest version |
| `hermes doctor` | Diagnose issues |
| `hermes --continue` | Resume last session |

## 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`:

```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
```

<Accordion label="Frequently asked questions" group="faq" expanded="true">

**Do I need a GPU to run Hermes Agent?**

No. Hermes Agent is the client — it sends requests to an LLM provider like OpenRouter. The provider runs the model on their hardware. Your server just needs enough RAM for the Python process (around 200MB).

**Can I use Hermes Agent with Ollama for fully local inference?**

Yes. Set `OPENAI_BASE_URL=http://localhost:11434/v1` and `OPENAI_API_KEY=ollama` in `~/.hermes/.env`. Or use `hermes model` and select "Custom endpoint." See our [Ollama Docker guide](/ollama-docker-install/) for setting up Ollama.

**How does the OpenRouter free tier work?**

OpenRouter offers several models at zero cost with rate limiting. You get a generous daily allowance. For heavier use, add credits to your OpenRouter account and switch to paid models. No changes needed on the Hermes side — same API key, different model name.

**Can I migrate from OpenClaw?**

Yes. Run `hermes claw migrate` and it imports your persona, memories, skills, API keys, and platform configs. Use `--dry-run` first to preview what gets migrated.

**Does Hermes work on Windows?**

Yes, natively. Run the PowerShell installer: `iex (irm https://hermes-agent.nousresearch.com/install.ps1)`. It bundles portable Git Bash when needed. WSL2 still works if you prefer a Linux environment. There is also a [Hermes Desktop](https://hermes-agent.nousresearch.com/) installer for macOS and Windows.

**Can I run Hermes with Docker Compose?**

Yes. Mount `~/.hermes` at `/opt/data`, run `nousresearch/hermes-agent setup` once, then `docker compose up -d` with `gateway run`. See the [Docker Compose section](#docker-compose-deployment) and the [official docker-compose.yml](https://github.com/NousResearch/hermes-agent/blob/main/docker-compose.yml).

**Can multiple people use one Hermes instance?**

Yes, through the messaging gateway. Each platform chat gets its own session. Multiple Telegram users or Discord channels can talk to the same instance with separate conversation histories. Use allowlists or DM pairing to control who has access.

**How does Hermes Agent compare to OpenFang?**

OpenFang focuses on autonomous agents (Hands) that work on schedules without prompting, and has 40 channel adapters with 16 security layers. Hermes focuses on the learning loop, voice mode, and a deeper memory system. Different strengths. See our [OpenFang setup guide](/openfang-setup-guide/) for the full comparison.

**How does it compare to CoPaw?**

CoPaw has a built-in web console and better support for Chinese messaging apps (DingTalk, Feishu, QQ). Hermes has the learning loop, voice mode, a built-in dashboard, and more terminal backend options. See our [CoPaw setup guide](/copaw-setup-guide/) for details.

**Is my data private?**

All data stays on your server. The only external calls go to your configured LLM provider. If you run local models via Ollama, nothing leaves your machine at all. Logs auto-redact secrets.

</Accordion>

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](/openclaw-alternatives/) roundup. If you want autonomous agents running on schedules, the [OpenFang setup guide](/openfang-setup-guide/) covers that. For a single Go binary on minimal hardware, see the [PicoClaw setup guide](/picoclaw-setup-guide/). And for the multi-channel web console approach, the [CoPaw setup guide](/copaw-setup-guide/) has the details. For the built-in UI and third-party web UIs, see the [Hermes dashboard guide](/hermes-dashboard-guide/) and [best Hermes dashboards](/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](/best-cheap-models-hermes-agent/) guide. If you are looking for a minimal coding agent to pair with Hermes, our [Pi coding agent setup guide](/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](/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](/top-ai-github-repos/).