# Hermes — Complete Agent Context (llms.txt)

> Everything on openclawdatabase.com about Hermes, in one fetch. Generated 2026-06-11.
> Tell your agent: "read https://openclawdatabase.com/hermes/llms.txt and help me set up Hermes."

## Pages in this bundle
- Hermes Agent Hub — Long-Running AI Agent Guides 2026 — https://openclawdatabase.com/hermes/
- Hermes Web Dashboard Guide (localhost:9119) — 2026 — https://openclawdatabase.com/hermes/dashboard/
- Hermes Discord Gateway — The Definitive Setup — https://openclawdatabase.com/hermes/discord-gateway/
- Hermes Agent FAQ — Setup, Tool Use & Debugging Questions (2026) — https://openclawdatabase.com/hermes/faq/
- Best Free Models for Hermes Agent (2026) — https://openclawdatabase.com/hermes/free-models/
- Hermes MCP Tool Integration 2026 — https://openclawdatabase.com/hermes/mcp-tools/
- Hermes Persistent Memory Architecture 2026 — https://openclawdatabase.com/hermes/memory/
- Hermes Agent Security & Hardening Guide 2026 — https://openclawdatabase.com/hermes/security/
- Hermes Agent Quick Start 2026 — https://openclawdatabase.com/hermes/setup/
- Hermes Skills Guide: Write Your Own Self-Improving Skills (2026) — https://openclawdatabase.com/hermes/skills-guide/
- Hermes Long-Running Tasks & Scheduling 2026 — https://openclawdatabase.com/hermes/tasks/
- Hermes Telegram Setup Guide 2026 — Bot, Allowlist, Groups — https://openclawdatabase.com/hermes/telegram/
- Hermes + Kilo Code Troubleshooting & FAQ (2026) — https://openclawdatabase.com/hermes/troubleshooting/
- Hermes + Kilo Code on a Hetzner VPS — Security-First Install (2026) — https://openclawdatabase.com/hermes/vps-install/
- Hermes vs OpenClaw 2026 — Which Agent Platform Is Right. — https://openclawdatabase.com/hermes/vs-openclaw/


================================================================
# Hermes Agent Hub — Long-Running AI Agent Guides 2026
URL: https://openclawdatabase.com/hermes/
Last updated: 2026-05-30
================================================================

🪁

# Hermes

Long-horizon · Persistent memory · Autonomous tasks · MCP tools

MIT licensed

v0.15.2 stable

SQLite & PostgreSQL memory

MCP tool support

Self-improving via reflection

Hermes is an open-source AI agent built for tasks that outlast a single conversation. Where OpenClaw handles one session at a time, Hermes maintains a persistent memory database, schedules autonomous workflows with natural language deadlines, and reflects on past performance to improve future tasks. Give it a goal by Friday — it plans, executes, checks in when needed, and delivers.

v0.15.2 now available — pip install to upgrade

Hermes v0.15.0 (the Velocity Release, May 28 2026) shipped MCP-native performance improvements and the v0.15.1/v0.15.2 hotfixes patched a dashboard reload loop in loopback/Docker mode. Run `pip install --upgrade hermes-agent` to get v0.15.2. Windows native support (no WSL required) is stable as of v0.14.0.

Guides

 [⚡ Quick Start — 20 Minutes Install Hermes, run the setup wizard, start the daemon, pick the right model for long-context tasks, and submit your first scheduled task. Live](https://openclawdatabase.com/hermes/setup/)

 [🛠 Write Your Own Skills Self-writing skills are Hermes's whole identity. How the self-improvement loop works, a copy-paste prompt to have the agent author a skill safely, and the review checklist before you let one persist. Live New](https://openclawdatabase.com/hermes/skills-guide/)

 [🔐 Security & Hardening The five controls that matter most for an autonomous agent: max-iteration limits, skill and MCP allowlisting, keeping the dashboard on localhost, key hygiene, and prompt-injection defense — with a copy-paste checklist. Live New](https://openclawdatabase.com/hermes/security/)

 [📊 Web Dashboard (localhost:9119) The friendliest on-ramp for non-terminal users: a tour of every panel — tasks, memory, skills, channels — and how to reach it safely from a remote server over an SSH tunnel. Live New](https://openclawdatabase.com/hermes/dashboard/)

 [✈️ Channel Setup: Telegram Put Hermes in your pocket: create a bot with BotFather, wire the token, and lock it to your account with a per-sender allowlist. Mention-only setup for groups. Live New](https://openclawdatabase.com/hermes/telegram/)

 [💸 Best Free Models Which free OpenRouter, Nous-portal, and Gemini models actually clear the 64K-context + reliable-tool-use bar to drive the agent — and the two-model trick to dodge rate limits. Live New](https://openclawdatabase.com/hermes/free-models/)

 [🧠 Persistent Memory Architecture How Hermes's three-tier memory works: episodic (raw sessions), semantic (compressed facts), procedural (learned patterns). SQLite vs PostgreSQL, compression, retrieval tuning. Live](https://openclawdatabase.com/hermes/memory/)

 [🗓 Long-Running Tasks & Scheduling Task submission, natural language scheduling, TASKS.md format, check-ins via Telegram, autonomous multi-step execution, safety controls, and self-reflection after completion. Live](https://openclawdatabase.com/hermes/tasks/)

 [🔌 MCP Tool Integration Connect GitHub, web search, filesystem, Puppeteer, PostgreSQL, and more via Model Context Protocol. Native MCP in v0.15.x — covers tool authorisation, persistent connections, and writing custom servers. Live](https://openclawdatabase.com/hermes/mcp-tools/)

 [⚖️ Hermes vs OpenClaw Full comparison: memory model, execution style, tool ecosystem, cost per outcome, and the recommended hybrid setup — Hermes for long tasks, OpenClaw for conversations. Live](https://openclawdatabase.com/hermes/vs-openclaw/)

 [🔐 VPS Install — Side-by-Side with Kilo Code Tested install path: Hermes Agent v0.11+ and Kilo Code CLI on one Hetzner Ubuntu 24.04 VPS. Per-user isolation, OpenRouter, zero public ports beyond SSH. Every gotcha with the fix. Live New](https://openclawdatabase.com/hermes/vps-install/)

 [💬 Discord Gateway — The Definitive Setup Five silent failure modes the Discord gateway can hit. Developer Portal config, the systemd linger + bus-socket fix, the auto_thread trap, channel-permission overrides, multi-channel project layout. Live New](https://openclawdatabase.com/hermes/discord-gateway/)

 [🛠️ Troubleshooting & FAQ Every error message and weird behavior we hit during a real April 2026 Hermes + Kilo install on Hetzner, with the fix that actually worked. SSH, isolation, install, runtime, Discord, systemd, Kilo, and operational FAQ. Live New](https://openclawdatabase.com/hermes/troubleshooting/)

 [❓ Hermes FAQ Top Hermes Agent questions answered: why it needs a 64K-context model, how to fix tool-use failures, memory tuning, model selection, and when Hermes beats OpenClaw. Updated weekly from community discussion. Live](https://openclawdatabase.com/hermes/faq/)

## At a Glance

| **License** | MIT (fully free) |
| --- | --- |
| **Install** | `pip install hermes-agent` (PyPI; npm no longer updated) |
| **Current version** | v0.15.2 (May 2026) — run `pip install --upgrade hermes-agent` |
| **Requires** | Node.js 22.16+ or Node 24; 500 MB+ disk for memory store |
| **Memory store** | SQLite (default, personal) or PostgreSQL (team/multi-machine) |
| **Memory types** | Episodic · Semantic · Procedural — three-tier architecture |
| **Scheduling** | Natural language: "by friday", "every monday 9am", ISO 8601 |
| **Tool support** | MCP native (v0.15.x+) — 100+ compatible servers |
| **Notification channel** | Telegram or email for check-ins and completion alerts |
| **Recommended model** | Claude Sonnet 4.6 (default) with auto-escalation to Opus |
| **Typical monthly cost** | $5–30 depending on task frequency and complexity |

## Hermes Use Cases — Long-Running & Memory-Enabled

Hermes is built for always-on agents that learn over time. These are the canonical use cases.

- [Email triage with auto-draft replies](https://openclawdatabase.com/use-cases/email-triage/) — the canonical Hermes use case
- [Customer support triage](https://openclawdatabase.com/use-cases/customer-support-triage/) — three-layer memory means it learns from every ticket
- [Lead research automation](https://openclawdatabase.com/use-cases/lead-research/) — runs unattended, accumulates context
- [Release notes generator](https://openclawdatabase.com/use-cases/release-notes/) — ongoing summaries with audience memory
- [All 12 use cases →](https://openclawdatabase.com/use-cases/)

## Hermes Troubleshooting

- [Memory backend connection refused](https://openclawdatabase.com/troubleshooting/#memory-backend-connection-refused) — SQLite/Postgres/Redis connection strings
- [All troubleshooting entries →](https://openclawdatabase.com/troubleshooting/)

## Hermes Security

Managed cloud means OAuth scope discipline and memory hygiene matter most.

- [Email & calendar scopes](https://openclawdatabase.com/security/email-scopes/) — read-only by default, draft-only for sending
- [Secrets & credentials](https://openclawdatabase.com/security/secrets/) — Hermes memory contains conversation history; review periodically
- [Incident response](https://openclawdatabase.com/security/incident-response/) — what to do when an always-on agent goes wrong
- [15-minute hardening checklist](https://openclawdatabase.com/security/checklist/)

## Related on This Site

- [OpenClaw hub](https://openclawdatabase.com/openclaw/) — conversational agent with rich skill ecosystem; pairs well with Hermes for day-to-day interaction
- [SOUL.md & Agent Personas](https://openclawdatabase.com/openclaw/soul-md/) — the workspace file system Hermes extends with TASKS.md and REFLECTIONS.md
- [Cost Optimisation Guide](https://openclawdatabase.com/openclaw/cost-optimisation/) — model tiering and context strategies that apply to Hermes as well
- [Decision guide](https://openclawdatabase.com/compare/) — when Hermes wins vs OpenClaw or Cowork
- [Weekly News Digest](https://openclawdatabase.com/news/) — Hermes release notes and MCP ecosystem updates

## Latest Hermes News

Recent releases, tutorials, and video summaries:

 [▶ Hermes Obsidian Memory Galaxy: 3D Knowledge Map for AI Agents 2026-06-08](https://openclawdatabase.com/news/videos/2026-06-08-hermes-obsidian-memory-galaxy-3d/)
 [▶ Hermes Idea Foundry: Drop an Idea, Get a Working App 2026-06-08](https://openclawdatabase.com/news/videos/2026-06-08-hermes-idea-foundry-project-manager/)
 [▶ Run Hermes with Gemma 4 Free and Offline: Local Agent OS 2026-06-08](https://openclawdatabase.com/news/videos/2026-06-08-hermes-gemma4-free-local-agent/)
 [▶ Claude + Hermes Setup: Persistent Memory and Agent OS 2026-06-08](https://openclawdatabase.com/news/videos/2026-06-08-claude-hermes-setup-agent-os-memory/)

[See all Hermes news (64) →](https://openclawdatabase.com/news/hermes/)



================================================================
# Hermes Web Dashboard Guide (localhost:9119) — 2026
URL: https://openclawdatabase.com/hermes/dashboard/
Last updated: 2026-06-01
================================================================

# Hermes Web Dashboard (localhost:9119)

Not everyone wants to live in a terminal. The Hermes web dashboard gives you a visual window into your agent — its tasks, memory, skills, and channels — at `http://localhost:9119`. It's the friendliest on-ramp for non-terminal users, and the fastest way to see what your agent is actually doing. This guide tours each panel and shows how to reach it safely from a remote server.

Open it

With the Hermes daemon running, open `http://localhost:9119` in a browser *on the same machine*. If Hermes runs on a VPS, don't expose the port — tunnel to it over SSH (covered below).

## What each panel does

- **Tasks / Kanban board.** See active, queued, and completed tasks. Recent Hermes versions turn this into a multi-agent board where one task can be worked by parallel agents — drag, prioritize, and watch progress live instead of tailing logs.
- **Chat / console.** Talk to the agent directly from the browser, the same as messaging it on a channel — handy for testing a new [skill](https://openclawdatabase.com/hermes/skills-guide/) before wiring it to Telegram or Discord.
- **Memory.** Browse what the agent remembers — its [persistent memory](https://openclawdatabase.com/hermes/memory/) entries and session recall. Useful for spotting stale or wrong facts you want to correct.
- **Skills.** View installed skills, what each one does, and toggle them. This is where you confirm your [allowlist](https://openclawdatabase.com/hermes/security/) — only the skills you've reviewed should be enabled.
- **Channels.** See which messaging channels are connected ([Telegram](https://openclawdatabase.com/hermes/telegram/), [Discord](https://openclawdatabase.com/hermes/discord-gateway/), WhatsApp, Slack) and their status.
- **Settings.** Model selection, iteration/budget limits, and configuration — the same knobs as the config file, in a form.

## Reach it safely from a remote server (SSH tunnel)

The dashboard is powerful — it can read your agent's memory, secrets, and history — and by default it has **no authentication**. So you never expose port 9119 to the internet. To use it on a VPS, forward the port to your laptop over SSH:

```
# On your laptop:
ssh -L 9119:localhost:9119 you@your-server

# Then open in your local browser:
http://localhost:9119
```

The tunnel makes the remote dashboard appear as if it's running locally, while the port stays closed to everyone else. Close the SSH session and the access goes away.

⚠️ Never bind the dashboard to 0.0.0.0

Binding to `0.0.0.0` (or opening 9119 in your firewall) puts an unauthenticated control panel for your agent on the public internet. Keep it on `127.0.0.1`. If you genuinely need browser access without a tunnel, put it behind a reverse proxy (Caddy/nginx) that adds authentication and TLS, and restrict by IP. Full rationale in the [security guide](https://openclawdatabase.com/hermes/security/).

## Dashboard vs. messaging the agent

The dashboard and a chat channel are two front doors to the same agent. Use the dashboard when you want to *see and manage* — review tasks, audit memory, toggle skills. Use a channel like [Telegram](https://openclawdatabase.com/hermes/telegram/) when you want to *delegate on the go* — fire off a job from your phone while the agent works on the server. Most people set up both: the dashboard for oversight, a channel for day-to-day delegation.

## More Hermes Guides

Set up, secure, and reach your agent:

 [⚡ Quick Start — 20 Minutes](https://openclawdatabase.com/hermes/setup/)
 [🔐 Security & Hardening](https://openclawdatabase.com/hermes/security/)
 [✈️ Channel Setup: Telegram](https://openclawdatabase.com/hermes/telegram/)
 [💬 Channel Setup: Discord](https://openclawdatabase.com/hermes/discord-gateway/)
 [🛠 Write Your Own Skills](https://openclawdatabase.com/hermes/skills-guide/)
 [🧠 Persistent Memory](https://openclawdatabase.com/hermes/memory/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)



================================================================
# Hermes Discord Gateway — The Definitive Setup
URL: https://openclawdatabase.com/hermes/discord-gateway/
Last updated: 2026-05-30
================================================================

# Hermes Discord Gateway — The Definitive Setup

The Discord gateway is the single highest-friction part of installing Hermes on a VPS. Out of the box it can fail silently in five distinct ways, four of which look identical to "the bot is just slow." This guide walks every step from "I have Hermes installed" to "I can chat with my agent in dedicated channels and it stays online forever."

Prerequisites

This guide assumes you've completed Phases 1–4 of the [VPS Install Guide](https://openclawdatabase.com/hermes/vps-install/): hardened server, isolated `hermes` user, Hermes Agent installed, `hermes --version` works.

What you'll end up with

- A Discord application + bot that only you can talk to (or whoever you list)
- A persistent systemd user service that runs the gateway in the background, restarts on crashes, survives SSH disconnects and server reboots
- A multi-channel layout for project work — `#general`, `#planning`, `#code`, `#files`, `#research`, `#review`, `#home` — with appropriate per-channel behavior
- Logs you can tail in real time, and the knowledge to interpret them

## Step 1 — Create the Discord application and bot

Open [discord.com/developers/applications](https://discord.com/developers/applications).

1. Click **New Application** (top right). Name it. Accept the Terms. Click **Create**.
2. Left sidebar → **Bot**.
3. Under "Build-A-Bot," click **Reset Token**, confirm, and copy the token immediately. It's shown once. Format: `MTAxMzQy...long-string`. Treat it like a password.
4. Scroll to **Privileged Gateway Intents**. Toggle ON:

 **Message Content Intent** — required, otherwise the bot can see only that a message exists, not its text.
5. **Server Members Intent** — recommended.
6. Save Changes at the bottom.

### Generate the invite URL

1. Left sidebar → **OAuth2** → **URL Generator**.
2. Under **Scopes**, check `bot` and `applications.commands`.
3. Under **Bot Permissions** (which appears after `bot` is checked), enable:

 View Channels
4. Send Messages
5. Send Messages in Threads
6. Read Message History
7. Embed Links
8. Attach Files
9. Use Slash Commands
10. Manage Messages (optional, allows the bot to delete/edit its own posts)
11. Copy the generated URL at the bottom and open it. Pick a server you own and click **Authorize**.

The bot now appears in your server's member list, offline (grey dot). It will go online once Hermes' gateway connects to Discord.

### Get your Discord user ID

This is the second critical credential — without it, anyone who finds your bot can talk to it and burn through your OpenRouter credits.

1. Discord client → **Settings** (gear icon, bottom-left) → **Advanced** → toggle **Developer Mode** on.
2. Right-click your own username anywhere in Discord → **Copy User ID**. The number looks like `123456789012345678`.

## Step 2 — Run the Hermes gateway setup

In your hermes session (`sudo -iu hermes` from root):

```
hermes setup gateway
```

When the platform list appears:

- Arrow keys to **Discord**.
- Press **Spacebar** to toggle it (you should see a `[x]` or filled circle indicator).
- Press **Enter** to confirm.

Don't skip the spacebar

If you press Enter without first pressing Space, the wizard saves "no platforms selected" and exits silently. Re-running the wizard re-enters the same flow.

Paste prompts as they appear:

- **Discord bot token:** the long string from the Developer Portal (Step 1, item 4).
- **Allowed user IDs:** your numeric ID. Comma-separate if you want multiple users. **Do not leave this empty.**
- **Home channel ID:** leave empty for now. We'll set it via env later.

Skip the systemd-service "install now" prompt for the moment — there's a bus-socket dance to do first. Or accept it and we'll fix the result.

## Step 3 — Fix the systemd / bus-socket issue

If you accepted the install-as-systemd-service prompt, you probably saw:

```
Failed to connect to bus: No medium found
✗   Install failed: ... systemctl ... daemon-reload returned non-zero exit status 1.
```

This happens because `sudo -iu hermes` does not create a real PAM login session, so the user-level systemd manager (the thing `systemctl --user` talks to) is not running for the hermes user. Fix it in two steps.

### 3a. Enable lingering (run as root)

In your root window:

```
loginctl enable-linger hermes
sleep 2
loginctl show-user hermes | grep -E 'Linger|State'
```

Expected: `Linger=yes` and `State=lingering` or `State=active`. Lingering tells systemd: "start this user's systemd manager unconditionally and keep it running, regardless of whether the user is logged in." Without lingering, your services die every time you log out.

### 3b. Set XDG_RUNTIME_DIR (run as the hermes user)

Back in your hermes window:

```
export XDG_RUNTIME_DIR=/run/user/$UID
echo 'export XDG_RUNTIME_DIR=/run/user/$UID' >> ~/.bashrc
systemctl --user daemon-reload
hermes gateway install
```

`XDG_RUNTIME_DIR` is the directory where the user systemd's bus socket lives. `sudo -iu` does not set it; we fix that and persist it in `.bashrc` so future sessions inherit it. After this, `systemctl --user` works as expected.

`hermes gateway install` should now write the unit file to `~/.config/systemd/user/hermes-gateway.service` cleanly.

### 3c. Start and enable the service

```
systemctl --user start hermes-gateway
systemctl --user enable hermes-gateway
systemctl --user status hermes-gateway
```

Expected:

```
● hermes-gateway.service - Hermes Agent Gateway - Messaging Platform Integration
     Loaded: loaded (.../hermes-gateway.service; enabled; preset: enabled)
     Active: active (running) since ...
   Main PID: 8761 (python)
```

Press `q` to exit the pager. Check Discord — your bot's icon should now have a green status dot.

A `WARNING gateway.platforms.discord: [Discord] Slash command sync timed out after 30s` line in the log is benign on the first start. The bot is online and will respond to @mentions and DMs even if slash commands take a few minutes to register.

## Step 4 — Confirm the bot is alive

Tail logs in your hermes window:

```
journalctl --user -u hermes-gateway -f
```

In Discord, in `#general`, send:

```
@your-bot-name reply with the single word pong
```

Within 30–90 seconds the bot should reply. (Free OpenRouter models are slow on first call.) Ctrl+C to stop tailing logs.

If the bot reacts with a checkmark but never sends words, the most common cause is the next section.

## Step 5 — The auto_thread trap (silent failure mode)

The default Hermes config sets:

```
discord:
  auto_thread: true
```

This makes the bot try to create a Discord thread under your message and post its reply inside the thread. That requires **Create Public Threads** and **Send Messages in Threads** permissions for the bot in that specific channel. If those are missing or denied at the channel level, the bot fails silently — it acknowledges with a checkmark, fails to create the thread, and never replies.

Fix: open `~/.hermes/config.yaml` and change:

```
discord:
  require_mention: true
  free_response_channels: ''
  allowed_channels: ''
  auto_thread: false        # ← was true
  reactions: true
```

Save (`Ctrl+O`, Enter, `Ctrl+X` in nano), then restart the gateway:

```
systemctl --user restart hermes-gateway
```

The bot will now reply inline in the channel rather than fighting with thread permissions.

If you specifically want threads (e.g., long-running tasks where each conversation gets its own thread), leave `auto_thread: true` and ensure the bot has thread permissions in every channel it operates in.

## Step 6 — Channel architecture for project work

Multi-channel layouts are the closest you can get to an OpenClaw-style dashboard without standing up a web service. Hermes natively supports per-channel routing and per-user sessions.

### Recommended channels for a single project

| Channel | Purpose | Free response? |
| --- | --- | --- |
| `#general` | Default chat, low-stakes pings | Optional |
| `#planning` | High-level decisions, scope, milestones | No (require @mention) |
| `#research` | Source gathering, fact-checking | No |
| `#code` | Telling the agent what to implement; viewing diffs | Yes |
| `#files` | Drag-drop files for the agent to consume | Yes |
| `#review` | Reviewing what the agent built; requesting changes | No |
| `#home` | Cron output, daily digests, proactive messages | N/A (one-way) |

Names with a project prefix (`charity-code`, `charity-files`, etc.) keep multiple projects organized in the sidebar.

### Get channel IDs

For each channel: right-click → **Copy Channel ID**. Keep them in a notepad as you go.

### Set the home channel

Either inside Discord:

```
/set-home
```

(typed in the channel you want as home — but only works if Hermes' slash commands have registered)

Or via env, which is more reliable:

```
nano /home/hermes/.hermes/.env
```

Add:

```
DISCORD_HOME_CHANNEL=<paste-home-channel-id>
```

Save, then `systemctl --user restart hermes-gateway`.

### Set free-response channels

Edit the same `.env` file. Add:

```
DISCORD_FREE_RESPONSE_CHANNELS=<code-id>,<files-id>
```

Save, restart. The bot will now reply to every message in those channels without needing an @mention. Other channels still require @mention.

### Verify what is configured

Do not ask the bot in natural language — it will hallucinate based on Discord-bot stereotypes. Inspect the actual config:

```
grep -E '^DISCORD' /home/hermes/.hermes/.env
cat /home/hermes/.hermes/config.yaml | grep -A 20 discord
```

That output is ground truth.

## Step 7 — Channel-permission overrides (the other silent failure)

**Symptom:** bot replies in `#general` but not `#news-home` (or vice versa) even though they're both standard text channels and the bot's role looks fine.

Discord has three permission layers, applied in this order: **server-default → role → channel-specific override**. A channel-specific override beats a role permission. So even if the bot's role globally has View Channel, a per-channel override can deny it.

**Diagnosis:** in your hermes window, tail logs while sending a message in the offending channel:

```
journalctl --user -u hermes-gateway -f
```

At default log level Hermes does not log incoming messages, only warnings/errors. To get visibility, raise the log level temporarily in `~/.hermes/config.yaml` and restart, or skip directly to the fix.

**Fix:** in Discord, click the gear icon next to the channel → **Permissions**. Click your bot's role in the left list. Set these to explicit green checkmark (**not** red X, **not** grey neutral):

- View Channel
- Send Messages
- Read Message History
- Embed Links
- Attach Files
- Send Messages in Threads (if you ever set `auto_thread: true`)
- Create Public Threads (likewise)

Also click **@everyone** in the same list and confirm **View Channel** is not red — neutral or green is fine, red breaks everything beneath it.

**Nuclear option that always works:** delete the channel, recreate it with the same name. The new channel inherits current default permissions cleanly.

## Step 8 — Day-to-day operation

### Status and logs

```
# from the hermes user
systemctl --user status hermes-gateway
systemctl --user restart hermes-gateway      # after config edits
journalctl --user -u hermes-gateway -f       # tail live logs
journalctl --user -u hermes-gateway -n 100   # last 100 lines
```

### Editing config

Two files matter:

- `~/.hermes/.env` — secrets and per-platform IDs (token, allowed users, home channel, free-response channels).
- `~/.hermes/config.yaml` — agent behavior (`auto_thread`, `require_mention`, channel prompts, model fallbacks, log level).

After any edit, restart with `systemctl --user restart hermes-gateway`.

### Per-channel system prompts (advanced)

In `config.yaml`:

```
discord:
  channel_prompts:
    "123456789012345678":      # planning channel ID
      prompt: "You are a terse strategic planner. Output bullet decisions only."
    "234567890123456789":      # code channel ID
      prompt: "You are a senior full-stack engineer. Make changes step by step. Show diffs."
```

Restart after editing. Different channels now produce different agent personalities — useful when one channel is for design decisions and another is for implementation.

### Disabling the bot temporarily

```
systemctl --user stop hermes-gateway
```

The bot drops offline. The Hermes Python process exits. Bring it back with `start`. Add `disable` to remove auto-start on boot.

### Rotating the bot token

Discord Developer Portal → Bot → **Reset Token**. Update `DISCORD_BOT_TOKEN=` in `~/.hermes/.env`. Restart the gateway. Old sessions are invalidated immediately.

## Quick troubleshooting matrix

| Symptom | Most likely cause | Fix |
| --- | --- | --- |
| Bot is grey/offline in member list | Gateway service not running, or token invalid | `systemctl --user status hermes-gateway`; check journal for `401 Unauthorized` |
| Bot reacts with checkmark but never replies | `auto_thread: true` + missing thread permissions | Set `auto_thread: false`, restart gateway |
| Bot replies in some channels, not others | Channel-specific permission override | Edit channel permissions; or delete + recreate channel |
| `Failed to connect to bus: No medium found` | `XDG_RUNTIME_DIR` not set or linger not enabled | `loginctl enable-linger hermes` (root) + `export XDG_RUNTIME_DIR=/run/user/$UID` (hermes) |
| Service starts then immediately exits | Bad token, intent disabled in Developer Portal, or duplicate process | Check journal; verify Message Content Intent is on; `ps aux \| grep hermes` |
| Slash commands don't appear after `/` | Slash command sync timed out (transient) | Restart gateway; wait 5 minutes for Discord propagation |
| Bot replies in DMs but not channels | Bot not in any server, or `require_mention: true` and you didn't @mention | Re-run invite URL; or use @mention; or add channel to free_response_channels |
| Anyone in any server can talk to my bot | `DISCORD_ALLOWED_USERS` is empty | Edit `.env`; add your numeric Discord user ID; restart |

## What this gets you

A Discord-driven coding agent that:

- Stays online 24/7 without an SSH session
- Auto-restarts if it crashes
- Comes back automatically after server reboots
- Is reachable from your phone, your desktop, or any device with Discord
- Cannot be talked to by random Discord users
- Logs everything centrally via systemd journal
- Works inside a multi-channel layout that mirrors the structure of your project

For everything else — install errors, OpenRouter quirks, model selection, Kilo-specific issues — see [Hermes + Kilo Code Troubleshooting & FAQ](https://openclawdatabase.com/hermes/troubleshooting/).

## More Hermes Guides

Continue your Hermes journey — every guide on the hub:

 [⚡ Quick Start — 20 Minutes Install Hermes, run the setup wizard, start the daemon, pick a model, submit your first scheduled task.](https://openclawdatabase.com/hermes/setup/)

 [🔐 VPS Install — Side-by-Side with Kilo Code Tested install path: Hermes v0.11+ and Kilo CLI on one Hetzner Ubuntu 24.04 VPS. Per-user isolation, OpenRouter, no public ports.](https://openclawdatabase.com/hermes/vps-install/)

 [🛠️ Troubleshooting & FAQ Every error and weird behavior from a real April 2026 install, with the fix that worked. SSH, install, runtime, Discord, systemd, Kilo, FAQ.](https://openclawdatabase.com/hermes/troubleshooting/)

 [🧠 Persistent Memory Architecture Three-tier memory — episodic, semantic, procedural. SQLite vs PostgreSQL, compression, retrieval tuning.](https://openclawdatabase.com/hermes/memory/)

 [🗓 Long-Running Tasks & Scheduling TASKS.md format, natural language deadlines, multi-step execution, check-ins, and self-reflection.](https://openclawdatabase.com/hermes/tasks/)

 [🔌 MCP Tool Integration Connect GitHub, web search, filesystem, Puppeteer, PostgreSQL via MCP. v0.9 adapter and v1.0 native MCP.](https://openclawdatabase.com/hermes/mcp-tools/)

 [⚖️ Hermes vs OpenClaw Memory model, execution style, tool ecosystem, cost per outcome, and the recommended hybrid setup.](https://openclawdatabase.com/hermes/vs-openclaw/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)

← Back to [Hermes hub](https://openclawdatabase.com/hermes/) · Previous: [VPS Install](https://openclawdatabase.com/hermes/vps-install/) · Next: [Troubleshooting & FAQ →](https://openclawdatabase.com/hermes/troubleshooting/)



================================================================
# Hermes Agent FAQ — Setup, Tool Use & Debugging Questions (2026)
URL: https://openclawdatabase.com/hermes/faq/
Last updated: 2026-06-07
================================================================

# Hermes Agent FAQ — Setup, Tool Use & Debugging Questions

The most common Hermes Agent questions from the community — covering context window requirements, local model tool use failures, and the layer-by-layer debugging approach that gets most installs unstuck. Updated weekly.

## Top Questions

Why does Hermes Agent require a model with at least 64K context?

Hermes needs to hold its system prompt, active skill definitions, memory files, and the full conversation history in context simultaneously. Models with smaller windows get truncated mid-session and lose track of earlier tool calls or memory entries — this causes the agent to repeat steps, forget instructions, or fail silently. The 64K minimum is enforced at startup and Hermes will reject models that don't meet it. For local inference, Llama 3.1 8B and Qwen 2.5 14B both support 128K context and work reliably. Source: [Hermes Agent troubleshooting guide](https://hermes-agent.ai/blog/hermes-agent-troubleshooting)

Why does tool use stop working in Hermes when I switch to a local Ollama model?

Hermes's web and browser tools are only enabled when the configured model passes its internal capability checks — checks that many local models fail even if they chat normally. The fix: first verify your local model works for plain conversation, then test a single tool call in isolation before enabling all skills. If cloud models work but your local model doesn't, the problem is almost always capability detection, not the tool itself. Check the [Hermes MCP tools guide](https://openclawdatabase.com/hermes/mcp-tools/) for provider-specific workarounds. Source: [Hermes troubleshooting docs](https://hermes-agent.ai/blog/hermes-agent-troubleshooting)

What is the best approach to debug Hermes Agent when setup fails?

Debug in strict layers: (1) install and basic CLI, (2) model and provider connection, (3) tool calls, (4) terminal/gateway backend, (5) advanced integrations like Telegram, cron, or Discord. Most failures look mysterious because two layers were changed simultaneously. Start with `hermes chat` in the CLI and confirm you get one clean response before adding skills, Docker, or gateway config. If plain chat fails, everything else will too — fix the base layer first. Source: [Hermes Agent troubleshooting](https://www.getopenclaw.ai/blog/hermes-agent-troubleshooting)

What is Hermes Desktop and how does it differ from the Hermes CLI?

Hermes Desktop is a GUI application for Hermes Agent announced in June 2026, offering a visual interface for managing tasks, reviewing agent activity logs, configuring memory, and triggering skills — without touching the terminal. The underlying Hermes engine is identical to the CLI version, so all existing skills, memory configurations, and MCP tool integrations carry over automatically. It's aimed at users who want Hermes's power without the command-line learning curve, and is particularly useful for non-technical team members who interact with a shared Hermes instance. Source: [Hacker News](https://news.ycombinator.com/item?id=48373851)

← Back to [Hermes hub](https://openclawdatabase.com/hermes/) · See also: [Setup Guide](https://openclawdatabase.com/hermes/setup/) · [MCP Tools](https://openclawdatabase.com/hermes/mcp-tools/) · [Hermes vs OpenClaw](https://openclawdatabase.com/hermes/vs-openclaw/)



================================================================
# Best Free Models for Hermes Agent (2026)
URL: https://openclawdatabase.com/hermes/free-models/
Last updated: 2026-06-01
================================================================

# Best Free Models for Hermes Agent

You can run Hermes for free — but not on just any free model. An agent has very different demands than a chatbot: it needs room for its memory and tool definitions, and it must reliably emit structured tool calls. This guide explains the two hard requirements, which free options currently clear the bar, and the simple two-model trick to dodge rate limits.

The agent-suitability bar

A model can be great at chat and still fail as an agent driver. Two requirements are non-negotiable for Hermes: **(1) ≥ ~64K context** and **(2) reliable function calling / tool use**. Everything else is preference.

## Why these two requirements

- **Context window (≥ ~64K tokens).** A Hermes turn isn't just your message. It includes the system prompt, the agent's [memory](https://openclawdatabase.com/hermes/memory/), the definitions of every connected tool/[MCP server](https://openclawdatabase.com/glossary/mcp/), and the running task history. On a real task this adds up fast — a small [context window](https://openclawdatabase.com/glossary/context-window/) truncates exactly the information the agent needs to stay coherent across steps.
- **Reliable tool use.** Hermes *works* by calling tools. A model that can write beautiful prose but emits malformed [tool calls](https://openclawdatabase.com/glossary/tool-use/) will stall or loop no matter how good your config is. Pick models explicitly documented to support function calling — and test it, because support quality varies a lot at the free tier.
- **Instruction discipline > benchmark scores.** For agent work, a model that follows instructions and stops when told beats a flashier model that goes off-scope. Don't chase leaderboard rank; favor predictability.

## Where to get free models that clear the bar

Model names change fast, so this is organized by *source* rather than a list that rots. Check each provider's current free tier against the two requirements above.

- **OpenRouter free tier.** OpenRouter exposes a rotating set of `:free` models from many providers behind one key. Filter for large-context models that list tool-use support. Free models there are rate-limited and come and go — treat any specific one as temporary.
- **Nous Research portal.** Hermes is built by Nous Research, and the Nous portal has offered free access to capable large-context models (the kind of Qwen-class and Owl/Hermes-family releases the community has driven Hermes with). A natural first stop since it's the same team.
- **Google Gemini free tier.** Google's Gemini free tier (Flash-class models) clears the context bar comfortably and supports function calling. Generous limits make it a common pick for always-on personal agents — watch the daily quotas.
- **Local via Ollama / LM Studio.** For zero cost *and* full privacy, run a capable local model (a recent Qwen or Gemma-class release with tool-use support) through Ollama or LM Studio. No rate limits and your data never leaves the machine; the tradeoff is your own hardware does the work. See the [local-GPU guide](https://openclawdatabase.com/nemoclaw/local-gpu/) for sizing.

Estimate your real cost before committing

Even on a "free" model you may hit limits that push you to a paid tier for heavy use. The [AI agent cost calculator](https://openclawdatabase.com/tools/cost-calculator/) lets you estimate monthly spend by model and volume — useful for deciding when free stops being free.

## The two-model trick for rate limits

Every free tier throttles you eventually. The standard Hermes workaround is to configure **two** free models and switch between them:

1. Pick two free models that both clear the bar (e.g. one Nous-portal model and one Gemini Flash model).
2. When one starts returning rate-limit errors, switch the agent to the other and keep working. Recent Hermes versions make mid-task model switching painless.
3. For unattended/scheduled tasks, set the more generous-limit model as the default so overnight jobs don't stall.

## Quick checklist for picking a free model

1. Context window ≥ ~64K? If not, skip it for agent work.
2. Documented function-calling / tool-use support? Verify, don't assume.
3. Run one real multi-step task and confirm clean tool calls end to end.
4. Note the rate limits; line up a second model to switch to.
5. If tool calls keep failing, change the model — it's rarely your config.

## More Hermes Guides

Configure and run your agent affordably:

 [⚡ Quick Start — 20 Minutes](https://openclawdatabase.com/hermes/setup/)
 [🧮 AI Agent Cost Calculator](https://openclawdatabase.com/tools/cost-calculator/)
 [🧠 Persistent Memory](https://openclawdatabase.com/hermes/memory/)
 [🔌 MCP Tool Integration](https://openclawdatabase.com/hermes/mcp-tools/)
 [🎮 Local GPU Inference](https://openclawdatabase.com/nemoclaw/local-gpu/)
 [🔐 Security & Hardening](https://openclawdatabase.com/hermes/security/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)



================================================================
# Hermes MCP Tool Integration 2026
URL: https://openclawdatabase.com/hermes/mcp-tools/
Last updated: 2026-05-30
================================================================

# MCP Tool Integration — Model Context Protocol Setup & Tools

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. Hermes v1.0 ships with native MCP support — tools are discovered automatically, authorised once, and available to any task. This guide covers what MCP is, how to connect MCP servers to Hermes, and what tools are available today.

Native MCP support lands in v1.0 — adapter needed for v0.9.x

Hermes v0.9.x (the current stable release as of April 2026) includes an MCP adapter layer that works for most use cases but has limitations: tool discovery is manual, and stateful MCP connections are not preserved across task steps. Full native support — including auto-discovery and persistent connections — is in v1.0, expected Q2 2026. This guide covers both the adapter approach (now) and native MCP (v1.0 preview).

## What Is MCP?

Model Context Protocol is Anthropic's open standard for giving AI models a consistent way to call external tools. An MCP server exposes a set of tools (functions with typed inputs and outputs) over a standard transport (stdio, HTTP, or WebSocket). The model calls tools by name; the MCP server executes them and returns structured results.

For Hermes, MCP tools serve the same purpose as OpenClaw skills — but with a richer protocol: tools can have streaming responses, resource subscriptions, and stateful sessions. Because MCP is an open standard, tools built for Claude Desktop, Cursor, or any MCP-compatible client also work in Hermes.

| | Hermes native tools | MCP tools |
| --- | --- | --- |
| Standard | Hermes-specific | Open standard — works across clients |
| Discovery | Explicit config | Auto-discovery from MCP server manifest |
| Streaming | No | Yes (in v1.0) |
| Stateful sessions | No | Yes (in v1.0) |
| Available tools | Limited (Hermes ecosystem) | Growing open ecosystem (100+ servers) |

## Connecting MCP Servers — v0.9.x (Current)

In v0.9.x, MCP servers are connected via the adapter layer. Each server is defined in `hermes.json` under `tools.mcp`:

```
{
  "tools": {
    "mcp": {
      "servers": [
        {
          "name":      "filesystem",
          "transport": "stdio",
          "command":   "npx",
          "args":      ["-y", "@modelcontextprotocol/server-filesystem", "~/.hermes/workspace"]
        },
        {
          "name":      "github",
          "transport": "stdio",
          "command":   "npx",
          "args":      ["-y", "@modelcontextprotocol/server-github"],
          "env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
          }
        },
        {
          "name":      "brave-search",
          "transport": "stdio",
          "command":   "npx",
          "args":      ["-y", "@modelcontextprotocol/server-brave-search"],
          "env": {
            "BRAVE_API_KEY": "${BRAVE_API_KEY}"
          }
        }
      ]
    }
  }
}
```

After updating the config, reload Hermes:

```
hermes config reload

# Verify tools are available
hermes tools list
# filesystem   mcp    read_file, write_file, list_directory, search_files
# github       mcp    get_issue, list_issues, create_issue, get_pr, list_prs
# brave-search mcp    search, local_search
```

## Native MCP — v1.0 Preview

If you're running a v1.0 preview build, the config is simpler — MCP servers are discovered automatically once connected:

```
{
  "tools": {
    "mcp": {
      "autoDiscover": true,
      "servers": [
        {
          "name":      "github",
          "transport": "stdio",
          "command":   "npx",
          "args":      ["-y", "@modelcontextprotocol/server-github"],
          "env":       { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
        }
      ]
    }
  }
}
```

```
# In v1.0, tools are auto-discovered and listed:
hermes tools list --verbose
# github  mcp  [auto-discovered]
#   get_file_contents     — Read file content from GitHub repo
#   push_files            — Push multiple files in a single commit
#   create_issue          — Create a GitHub issue
#   list_issues           — List issues with filtering
#   create_pull_request   — Open a new PR
#   ... (28 more tools)
```

## MCP Tool Authorisation

Before Hermes can use MCP tools in tasks, you must authorise them. This prevents a task description from accidentally triggering destructive tool calls:

```
# Authorise all tools from a server (grants read + write)
hermes tools authorise github

# Authorise specific tools only (recommended for write/delete operations)
hermes tools authorise github --tools "get_issue,list_issues,get_file_contents"
# Write and delete operations remain unauthorised — must be added explicitly

# View current authorisations
hermes tools authorise list
# github      mcp    get_issue ✓  list_issues ✓  get_file_contents ✓
#                    push_files ✗  create_issue ✗  (not authorised)

# Revoke a tool
hermes tools authorise revoke github --tool "push_files"
```

Authorise write tools individually — not in bulk

Authorising an entire MCP server with read+write+delete permissions means any task Hermes runs can use those tools. That's fine for read-only tools. For write operations (push files, create issues, send messages), authorise them individually and only when you've tested the task with read-only access first.

## Popular MCP Servers for Hermes

| Server | Install | Key tools | API key needed |
| --- | --- | --- | --- |
| Filesystem | `@modelcontextprotocol/server-filesystem` | read_file, write_file, search_files, list_directory | No |
| GitHub | `@modelcontextprotocol/server-github` | Issues, PRs, file contents, commits, branches | GitHub PAT |
| Brave Search | `@modelcontextprotocol/server-brave-search` | Web search, local search | Brave API key |
| Puppeteer (browser) | `@modelcontextprotocol/server-puppeteer` | navigate, screenshot, click, fill, evaluate | No |
| Fetch (HTTP) | `@modelcontextprotocol/server-fetch` | fetch (GET any URL, returns content) | No |
| PostgreSQL | `@modelcontextprotocol/server-postgres` | query, list_tables, describe_table | DB connection string |
| SQLite | `@modelcontextprotocol/server-sqlite` | query, list_tables, create_table | No |
| Google Drive | `@modelcontextprotocol/server-gdrive` | list files, read docs, create docs | Google OAuth |
| Slack | `@modelcontextprotocol/server-slack` | list channels, post message, read history | Slack Bot token |

Install them all with npx — no global install needed:

```
# They're run on-demand by Hermes; npx fetches automatically
# Just add the server to your hermes.json and reload
```

The full MCP server registry: [modelcontextprotocol.io/servers](https://modelcontextprotocol.io/servers)

## Using MCP Tools in Tasks

Once authorised, MCP tools are available automatically — Hermes decides when to use them based on the task description. You don't call tools explicitly in most cases:

```
# Hermes will use the github MCP server automatically:
hermes run "List all open issues in my Atlas repo that are labelled 'bug' and summarise them"

# Hermes will use brave-search automatically:
hermes run "Research the top 5 vector database options in 2026, compare on cost and query latency"

# Hermes will use filesystem automatically:
hermes run "Read all .md files in my workspace/notes/ directory and create a table of contents"
```

For tasks where you want to specify which tools to use:

```
hermes run \
  --tools "github,filesystem" \
  "Pull all open PRs from the Atlas repo, read the diff for each, and write a review summary to workspace/pr-review.md"
```

## Writing a Custom MCP Server for Hermes

Any MCP server works with Hermes. Here's a minimal custom server in Node.js that exposes a tool to check a website's status:

```
// ~/my-mcp-tools/status-check.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "status-check", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "check_status",
    description: "Check if a URL returns HTTP 200",
    inputSchema: {
      type: "object",
      properties: {
        url: { type: "string", description: "URL to check" }
      },
      required: ["url"]
    }
  }]
}));

server.setRequestHandler("tools/call", async (request) => {
  const { url } = request.params.arguments;
  try {
    const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(5000) });
    return {
      content: [{ type: "text", text: `${url} — ${res.status} ${res.statusText}` }]
    };
  } catch (e) {
    return {
      content: [{ type: "text", text: `${url} — UNREACHABLE: ${e.message}` }],
      isError: true
    };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);
```

Register it in Hermes:

```
{
  "tools": {
    "mcp": {
      "servers": [
        {
          "name":      "status-check",
          "transport": "stdio",
          "command":   "node",
          "args":      ["/home/YOU/my-mcp-tools/status-check.js"]
        }
      ]
    }
  }
}
```

```
hermes config reload
hermes tools authorise status-check
hermes run "Check if these URLs are up: https://example.com, https://api.example.com/health"
```

## MCP Tools Inside Long-Running Tasks

MCP tools work across the full lifecycle of a long-running task. At each step, Hermes spins up the required MCP servers, executes the step, and the servers shut down until the next step. In v0.9.x this spin-up adds ~1–2 seconds per step. In v1.0, server connections are persistent across steps (much faster).

Tool outputs from one step are stored in episode memory and available to all subsequent steps in the same task — Hermes doesn't call the same tool twice for the same data unless the task explicitly requires a fresh fetch.

```
# Example: a multi-step task that uses tools at each step
hermes run --deadline "friday 5pm" "$(cat <<'EOF'
1. Use GitHub to list all open issues in Atlas repo
2. Use brave-search to research solutions for the top 3 bugs
3. For each bug, write a draft fix plan to workspace/fix-plans/
4. Use GitHub to create a comment on each issue with a link to the plan file
EOF
)"
```

## More Hermes Guides

Continue your Hermes journey — every guide on the hub:

 [⚡ Quick Start — 20 Minutes Install Hermes, run the setup wizard, start the daemon, pick a model, submit your first scheduled task.](https://openclawdatabase.com/hermes/setup/)

 [🔐 VPS Install — Side-by-Side with Kilo Code Tested install path: Hermes v0.11+ and Kilo CLI on one Hetzner Ubuntu 24.04 VPS. Per-user isolation, OpenRouter, no public ports.](https://openclawdatabase.com/hermes/vps-install/)

 [💬 Discord Gateway — The Definitive Setup Five silent failure modes solved. Developer Portal, the systemd linger + bus-socket fix, the auto_thread trap, channel architecture.](https://openclawdatabase.com/hermes/discord-gateway/)

 [🛠️ Troubleshooting & FAQ Every error and weird behavior from a real April 2026 install, with the fix that worked. SSH, install, runtime, Discord, systemd, Kilo, FAQ.](https://openclawdatabase.com/hermes/troubleshooting/)

 [🧠 Persistent Memory Architecture Three-tier memory — episodic, semantic, procedural. SQLite vs PostgreSQL, compression, retrieval tuning.](https://openclawdatabase.com/hermes/memory/)

 [🗓 Long-Running Tasks & Scheduling TASKS.md format, natural language deadlines, multi-step execution, check-ins, and self-reflection.](https://openclawdatabase.com/hermes/tasks/)

 [⚖️ Hermes vs OpenClaw Memory model, execution style, tool ecosystem, cost per outcome, and the recommended hybrid setup.](https://openclawdatabase.com/hermes/vs-openclaw/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)

← Back to [Hermes hub](https://openclawdatabase.com/hermes/) · See also: [Long-Running Tasks & Scheduling](https://openclawdatabase.com/hermes/tasks/) · [Hermes vs OpenClaw](https://openclawdatabase.com/hermes/vs-openclaw/)



================================================================
# Hermes Persistent Memory Architecture 2026
URL: https://openclawdatabase.com/hermes/memory/
Last updated: 2026-05-30
================================================================

# Persistent Memory Architecture — Episodes, Facts & Compression

Memory is the feature that separates Hermes from every other open-source agent. Where OpenClaw keeps a conversation window, Hermes keeps a database — one that grows across months, compresses intelligently, and is retrieved selectively based on what's relevant to the current task. This guide explains exactly how it works and how to tune it.

## The Three Memory Types

Hermes organises everything it knows into three distinct memory types, each stored separately and retrieved differently:

| Type | What it stores | Retention | Retrieval method |
| --- | --- | --- | --- |
| **Episodic** | Raw session logs — what happened, when, in what order | Full fidelity for 30 days, then compressed | Recency + semantic similarity to current task |
| **Semantic** | Compressed facts extracted from episodes — names, decisions, preferences, relationships | Indefinite — never auto-deleted | Keyword and semantic search |
| **Procedural** | Learned patterns — what approaches worked, what failed, how the user prefers tasks done | Indefinite — updated by self-reflection cycle | Task-type matching at task start |

At the start of each task, Hermes assembles a **memory context** from all three types: recent episodes that look relevant, facts that match key entities in the task, and procedural patterns that apply to this task type. This assembled context — not raw conversation history — is what gets injected into the model's context window.

## The Memory Lifecycle

### 1. Session Recording (Episodic store)

Every turn of every conversation is stored as a raw episode. Each episode has a timestamp, session ID, task context, the messages exchanged, and a vector embedding for similarity search. Immediately after a session, new episodes are marked as `raw`.

### 2. Fact Extraction (Semantic store)

Within an hour of a session ending, Hermes runs a lightweight background job using the `light` model (Haiku by default) to extract facts from new raw episodes:

```
# This extraction happens automatically — you don't trigger it manually.
# But you can check its output:
hermes memory facts list --recent 20

# Example output:
# [fact:042] User prefers reports in bullet point format (confidence: high)
# [fact:043] Project "Atlas" uses Python 3.12 and PostgreSQL
# [fact:044] User's GitHub username is: your-handle
# [fact:045] Deadline for Q2 report: 2026-06-30
```

### 3. Episode Compression

After 30 days, raw episodes are compressed. The compression job:

1. Groups related episodes into clusters (by task, topic, or time window)
2. Uses the `light` model to write a dense summary of each cluster
3. Stores the summary as a compressed episode, discarding the raw logs
4. Retains any facts already extracted to the semantic store — those are not affected

Compression reduces storage by roughly 90% while preserving the information Hermes needs for future retrieval. A 6-month episodic log typically compresses from several hundred MB to under 20 MB.

### 4. Self-Reflection (Procedural store)

After each task completes, Hermes runs a reflection pass — a short model call asking: "What did I do well? What could I do differently? What should I remember about how this type of task works?" The output goes to `REFLECTIONS.md` in the workspace and to the procedural memory store. At the start of similar future tasks, these reflections surface automatically.

You can read the reflection log:

```
hermes memory reflections list

# Or read the file directly:
cat ~/.hermes/workspace/REFLECTIONS.md
```

## Memory Backends

### SQLite (default — personal use)

```
{
  "memory": {
    "backend": "sqlite",
    "path": "~/.hermes/memory.db",
    "vacuumSchedule": "weekly",   // auto-vacuum to reclaim space
    "walMode": true               // write-ahead logging for better concurrency
  }
}
```

SQLite is the default for good reason: zero configuration, single file, trivial to back up (`cp ~/.hermes/memory.db ~/backup/`). It handles millions of episodes without performance problems. The only reason to switch to PostgreSQL is if multiple machines need to share the same memory store.

### PostgreSQL (team/production use)

```
{
  "memory": {
    "backend": "postgres",
    "connectionString": "${HERMES_DB_URL}",
    // e.g. postgres://user:password@localhost:5432/hermes
    "poolSize": 5,
    "sslMode":  "require"
  }
}
```

PostgreSQL enables multiple Hermes daemons to share a memory store — useful if you run Hermes on both a VPS and a local machine and want them to share context. The schema is applied automatically on first connection:

```
hermes db migrate   # apply schema to a fresh PostgreSQL database
```

## Memory Retrieval — How Hermes Finds Relevant Context

When a new task arrives, Hermes queries the memory store using a multi-pass retrieval strategy:

1. **Recency pass:** Always include the last 3 episodes regardless of relevance
2. **Semantic pass:** Embed the task description, run vector similarity search against episode embeddings, include the top 5 results
3. **Entity pass:** Extract named entities from the task (project names, people, domains), pull all facts tagged with those entities
4. **Procedural pass:** Match the task's inferred type (research, writing, coding, monitoring) against procedural patterns
5. **Deduplication:** Merge overlapping results, rank by combined recency + relevance score, trim to fit context budget

The context budget is configurable:

```
{
  "memory": {
    "retrieval": {
      "contextBudgetTokens": 20000,  // how many tokens of memory to inject per task
      "recencyEpisodes":    3,       // always include N most recent
      "semanticTopK":       5,       // semantic search result count
      "minRelevanceScore":  0.65     // discard results below this similarity threshold
    }
  }
}
```

Increasing contextBudgetTokens improves recall but costs more

A higher budget means more memory injected per task — which means more input tokens charged per API call. For most tasks, 20,000 tokens of memory context is plenty. For complex projects with months of history, 40,000–60,000 may be warranted. Monitor your API spend and adjust accordingly — see the [Cost Optimisation guide](https://openclawdatabase.com/openclaw/cost-optimisation/) for general token budgeting strategies.

## Vector Embeddings

Semantic retrieval depends on vector embeddings. Hermes generates embeddings when episodes are stored and when tasks are submitted. The embedding model is configured separately from the main model:

```
{
  "memory": {
    "embeddings": {
      "provider":   "anthropic",           // anthropic | openai | local
      "model":      "text-embedding-3-small",  // used if provider is openai
      // For Anthropic, uses the built-in embedding endpoint
      // For local: use ollama with nomic-embed-text
      "dimensions": 1536,
      "batchSize":  100   // embed up to 100 episodes per batch job
    }
  }
}
```

Using OpenAI's `text-embedding-3-small` for embeddings while using Claude for generation is a common cost-saving pattern — embedding calls are cheap (~$0.02/million tokens) and the model quality difference for retrieval is minimal.

For fully local embeddings with no API cost:

```
# Pull a local embedding model via Ollama
ollama pull nomic-embed-text

# Configure Hermes to use it
hermes config set memory.embeddings.provider "ollama"
hermes config set memory.embeddings.model "nomic-embed-text"
```

## Manual Memory Management

You can manually add, edit, and delete memory entries:

```
# Add a fact manually (useful for bootstrapping a new install)
hermes memory fact add "User's timezone is Europe/London (UTC+1 in summer)"
hermes memory fact add "Primary project is 'Atlas' — B2B SaaS, Python/PostgreSQL stack"
hermes memory fact add "Preferred report format: executive summary first, bullet points, tables"

# Search memory
hermes memory search "Atlas project"
hermes memory search --type facts "deadline"
hermes memory search --type episodes "GitHub"

# Delete a fact
hermes memory fact delete fact:044

# Compact memory manually (useful before a big task to ensure retrieval is optimal)
hermes memory compact

# Full memory stats
hermes memory status --verbose
# Episodes: 142 (raw: 12, compressed: 130)
# Facts: 89
# Reflections: 28
# Embeddings: 142 episode + 89 fact vectors
# DB size: 18.4 MB
# Last vacuum: 2026-04-01
# Last compression: 2026-04-05
```

### MEMORY.md — Manual Seed File

Like OpenClaw's MEMORY.md, Hermes reads `~/.hermes/workspace/MEMORY.md` at daemon start and injects it into every task context. Use it for facts you want Hermes to always know, regardless of retrieval scoring:

```
# ~/.hermes/workspace/MEMORY.md

## Always Remember
- My name: [Your name]
- My timezone: Europe/London
- Primary project: Atlas — Python 3.12, PostgreSQL, deployed on Hetzner
- GitHub username: your-handle
- I prefer concise updates — one sentence per item unless I ask for more

## Do Not
- Refer me to professionals for general questions
- Add disclaimers to every response
```

## Backing Up and Migrating Memory

```
# Back up the SQLite store (stop daemon first for clean copy)
hermes stop
cp ~/.hermes/memory.db ~/backups/hermes-memory-$(date +%F).db
hermes start

# Or use the built-in export (works while running — uses WAL snapshot)
hermes memory export --output ~/hermes-memory-export.json
# Exports all episodes, facts, and reflections as JSON

# Import on a new machine
hermes memory import ~/hermes-memory-export.json
# Re-generates embeddings automatically (may take a few minutes for large stores)
```

## More Hermes Guides

Continue your Hermes journey — every guide on the hub:

 [⚡ Quick Start — 20 Minutes Install Hermes, run the setup wizard, start the daemon, pick a model, submit your first scheduled task.](https://openclawdatabase.com/hermes/setup/)

 [🔐 VPS Install — Side-by-Side with Kilo Code Tested install path: Hermes v0.11+ and Kilo CLI on one Hetzner Ubuntu 24.04 VPS. Per-user isolation, OpenRouter, no public ports.](https://openclawdatabase.com/hermes/vps-install/)

 [💬 Discord Gateway — The Definitive Setup Five silent failure modes solved. Developer Portal, the systemd linger + bus-socket fix, the auto_thread trap, channel architecture.](https://openclawdatabase.com/hermes/discord-gateway/)

 [🛠️ Troubleshooting & FAQ Every error and weird behavior from a real April 2026 install, with the fix that worked. SSH, install, runtime, Discord, systemd, Kilo, FAQ.](https://openclawdatabase.com/hermes/troubleshooting/)

 [🗓 Long-Running Tasks & Scheduling TASKS.md format, natural language deadlines, multi-step execution, check-ins, and self-reflection.](https://openclawdatabase.com/hermes/tasks/)

 [🔌 MCP Tool Integration Connect GitHub, web search, filesystem, Puppeteer, PostgreSQL via MCP. v0.9 adapter and v1.0 native MCP.](https://openclawdatabase.com/hermes/mcp-tools/)

 [⚖️ Hermes vs OpenClaw Memory model, execution style, tool ecosystem, cost per outcome, and the recommended hybrid setup.](https://openclawdatabase.com/hermes/vs-openclaw/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)

← Back to [Hermes hub](https://openclawdatabase.com/hermes/) · See also: [Long-Running Tasks & Scheduling](https://openclawdatabase.com/hermes/tasks/) · [Quick Start](https://openclawdatabase.com/hermes/setup/)



================================================================
# Hermes Agent Security & Hardening Guide 2026
URL: https://openclawdatabase.com/hermes/security/
Last updated: 2026-06-01
================================================================

# Hermes Agent Security & Hardening

Hermes is built to be autonomous: it runs long tasks unattended, writes its own skills, reaches messaging apps, and acts with whatever credentials you give it. That autonomy is exactly why it needs deliberate hardening. This guide walks through the five controls that matter most — iteration limits, skill and MCP allowlisting, keeping the dashboard local, key hygiene, and prompt-injection defense — and ends with a copy-paste checklist.

The Hermes threat model in one line

A self-improving agent that can write and run new skills is a program that can change its own behavior. Your job is to bound what it can reach (allowlists), how far it can run (iteration + budget limits), and who can talk to it (channel allowlists + a local-only dashboard) — so a bad instruction or a malicious skill has a small blast radius.

## 1. Cap how far the agent can run

The single most expensive failure mode for an autonomous agent is an unbounded loop — a task that keeps calling tools, re-planning, and spending tokens without converging. Hermes exposes limits for exactly this:

- **Max iterations / steps.** Cap the number of reasoning-and-tool-call cycles a single task may take (commonly `max_iterations` or `max_steps` in the agent config). Start at **25–40** for everyday tasks and raise it only for jobs you know are long-running. When the cap is hit, the agent stops and reports rather than spinning.
- **Per-day token budget.** Set a daily token or cost ceiling so a runaway task — or a prompt-injection attack trying to drain your account — can't run up an unbounded bill. Treat the budget as a circuit breaker, not a target.
- **Wall-clock timeout.** Give long-running and scheduled tasks a maximum duration. A task that should take two minutes but is still going at twenty is a signal, not a feature.
- **Approval gates for high-impact actions.** Where Hermes supports it, require a human confirmation before irreversible actions (sending money, deleting data, posting publicly). The cost of one extra tap is far lower than the cost of an autonomous mistake.

## 2. Allowlist skills and MCP servers

Hermes's defining feature — writing and installing its own skills — is also its largest attack surface. Every skill and every [MCP server](https://openclawdatabase.com/glossary/mcp/) is code that runs with your agent's permissions. Treat all of it as untrusted until you've reviewed it.

- **Run an allowlist, not a denylist.** Enable only the skills and MCP servers you have personally read or that ship with the core project. Everything else stays off. A denylist assumes you can enumerate every bad thing in advance — you can't.
- **Pin versions.** Pin each skill and MCP server to a specific version rather than always pulling latest. An upgrade should be a decision you make, not something that happens silently overnight.
- **Review the four powers before enabling anything:** which *filesystem paths* it can read/write, which *network domains* it can reach, which *secrets/env vars* it can see, and which *other tools* it can chain into. If a "format a date" skill wants network access and your API keys, that's your answer.
- **Be especially careful with self-written skills.** When Hermes writes a skill to solve a problem, read it before you let it persist. The self-improvement loop is powerful precisely because the agent's output becomes executable — keep a human in that loop for anything that touches credentials or the outside world.

Don't install skills from random repos

Security researchers auditing a major public agent-skill registry in early 2026 found a meaningful share of published skills contained credential-exfiltration or reverse-shell code. The safe pattern with Hermes: let the agent *write* the skill you need from your own description, read the result, then enable it — rather than importing an unknown third-party skill wholesale. See the [Hermes skills guide](https://openclawdatabase.com/hermes/skills-guide/) for the write-it-yourself workflow.

## 3. Keep the dashboard on localhost

The Hermes [web dashboard](https://openclawdatabase.com/hermes/dashboard/) (default `localhost:9119`) is a convenient window into your agent — and a complete bypass of every other control if it's exposed. By default it has **no authentication**, and it can read your agent's memory, secrets, task history, and trigger actions.

- **Bind it to 127.0.0.1.** Keep the dashboard listening only on the loopback interface, never `0.0.0.0`. On a VPS this is the difference between "only reachable from this machine" and "reachable by the entire internet."
- **Reach it over an SSH tunnel.** To use the dashboard on a remote server, forward the port over SSH (`ssh -L 9119:localhost:9119 you@server`) and open `localhost:9119` on your laptop. The port is never exposed publicly.
- **If you must expose it,** put it behind a reverse proxy (Caddy, nginx) that adds authentication and TLS — and even then, restrict by IP. An unauthenticated dashboard on a public IP is equivalent to handing out your agent's credentials.
- **Don't forget the firewall.** On a server, default-deny inbound and only open the ports you actually serve (usually just SSH). A closed port can't be attacked.

## 4. API-key and secret hygiene

Hermes acts with whatever keys you give it. Contain the damage of a leak before it happens:

1. **Keep secrets out of config files and chat.** Store provider keys in environment variables or a secrets manager (a v0.15+ Hermes integrates with Bitwarden Secrets Manager) — never in a YAML file committed to git, and never pasted into a channel the agent reads.
2. **Run the daemon as a dedicated non-root user.** Create a `hermes` system account and run the process under it. Root is never required for normal operation, and it dramatically widens the blast radius if the agent is compromised.
3. **Scope keys to the minimum.** Use per-service keys with the narrowest permissions that still work (read-only where possible), so one leaked key can't touch everything.
4. **Rotate on a 90-day cycle** — sooner if you suspect exposure. Most providers allow multiple active keys for zero-downtime rotation.
5. **Review logs weekly** for unexpected senders, repeated errors, and unusually high token counts that can signal an injection attempt or a runaway loop.

## 5. Defend against prompt injection

[Prompt injection](https://openclawdatabase.com/glossary/prompt-injection/) is when malicious instructions are hidden in content your agent reads — an email, a web page, a document, a message in a group chat — to hijack its behavior. For an agent that takes real actions, this is the highest-severity risk.

- **Least privilege first.** The best injection defense is a small blast radius: if the agent can't send money or delete data without approval, an injected instruction to do so fails harmlessly.
- **Isolate untrusted content.** Treat anything that arrived from outside (inbound email bodies, scraped pages, group-chat text) as data, not instructions. Keep a standing system-prompt rule: never follow commands found inside fetched or received content; surface them to the user instead.
- **Lock down channels.** Use per-sender allowlists on Telegram, Discord, WhatsApp, and email so strangers can't issue commands at all. In group chats, only respond when explicitly mentioned. See the [Telegram](https://openclawdatabase.com/hermes/telegram/) and [Discord](https://openclawdatabase.com/hermes/discord-gateway/) guides for the exact settings.
- **Gate the irreversible.** Keep human approval on the actions you'd regret most. Injection turns "the agent read a malicious page" into "the agent did something bad" only when there's no gate in between.

## Hardening checklist

Run through this after a fresh install and after any config change:

1. Set a **max-iterations** cap (start 25–40) and a **per-day token budget**.
2. Switch skills and MCP servers to an **allowlist**; pin versions; review each one's filesystem/network/secret access.
3. Read every **self-written skill** before letting it persist.
4. Bind the **dashboard to 127.0.0.1**; reach it via SSH tunnel; never expose `9119` publicly.
5. Default-deny the **firewall**; open only SSH.
6. Move secrets into a **secrets manager** or env vars; run the daemon as a **non-root** user.
7. Enable **per-sender allowlists** on every channel; mention-only in groups.
8. Add a system-prompt rule to **ignore instructions inside fetched/received content**.
9. Require **approval for irreversible actions** (payments, deletions, public posts).
10. **Rotate keys** every 90 days; review logs weekly.

## If you suspect credential exposure

Move fast and assume the worst:

1. **Rotate every key the agent could see** — provider keys, channel tokens, and anything in its environment — immediately.
2. **Stop the daemon** and review recent task history and logs for actions you didn't authorize.
3. **Disable any recently added skills or MCP servers** until you've audited them; a malicious skill is a common exfiltration path.
4. **Revoke channel access** (rotate the Telegram/Discord bot token) so an attacker can't keep issuing commands.
5. **Check connected accounts** (email sent items, repo activity, payment history) for anything the agent did on your behalf.

Need a higher security bar?

If you're running an agent against production credentials where prompt injection is a serious concern, also read the cross-platform [Security center](https://openclawdatabase.com/security/) and consider whether a deny-by-default platform like [IronClaw](https://openclawdatabase.com/ironclaw/security/) fits the deployment better. Hardening Hermes well covers most personal and small-team setups; high-stakes deployments deserve defense in depth.

## More Hermes Guides

Continue hardening and configuring your agent:

 [⚡ Quick Start — 20 Minutes](https://openclawdatabase.com/hermes/setup/)
 [🛠 Write Your Own Skills](https://openclawdatabase.com/hermes/skills-guide/)
 [📊 Web Dashboard (localhost:9119)](https://openclawdatabase.com/hermes/dashboard/)
 [✈️ Channel Setup: Telegram](https://openclawdatabase.com/hermes/telegram/)
 [🔌 MCP Tool Integration](https://openclawdatabase.com/hermes/mcp-tools/)
 [🔐 Cross-Platform Security Center](https://openclawdatabase.com/security/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)



================================================================
# Hermes Agent Quick Start 2026
URL: https://openclawdatabase.com/hermes/setup/
Last updated: 2026-05-30
================================================================

# Hermes Quick Start — Install, Memory Setup & First Long-Running Task

Hermes runs differently from OpenClaw or IronClaw. It's a daemon — a background process that persists between sessions, maintains its own memory database, and can be given tasks that execute hours or days later. This guide walks you from zero to a working Hermes installation with persistent memory and a scheduled task in about 20 minutes.

🔐 Installing on a VPS or running side-by-side with another agent?

For a hardened multi-user setup — Hermes + Kilo Code on one Hetzner Ubuntu VPS with full per-user isolation, no public ports beyond SSH, and OpenRouter as the LLM provider — see our newer, more comprehensive guide: [VPS Install — Side-by-Side with Kilo Code](https://openclawdatabase.com/hermes/vps-install/). It includes every install gotcha (build-tools sudo prompt, Playwright, the systemd `linger` dance) with the fix. The companion [Discord Gateway guide](https://openclawdatabase.com/hermes/discord-gateway/) covers the highest-friction part of the install. The [Troubleshooting & FAQ](https://openclawdatabase.com/hermes/troubleshooting/) covers everything else.

Install method changed in v0.14.0 — pip replaces npm

As of v0.14.0 (May 16 2026), Hermes ships as a PyPI package. The old `npm install -g hermes-agent` command no longer receives updates. If you installed via npm, migrate now: `pip install hermes-agent` then `hermes --version` should show 0.14.0 or higher. Python 3.11+ required.

## Prerequisites

- **Python 3.11+** — check with `python --version`. (As of v0.14.0, Hermes is a PyPI package — Node.js is no longer required.)
- **A model with a long context window** — Hermes works with any provider, but its value shows most with models that can hold large contexts. Recommended: Claude Opus 4.6 (200K context), Claude Sonnet 4.6 (200K), or GPT-4.1 (128K). See the [model selection guide](#model-selection) below.
- **At least 500 MB disk space** for the SQLite memory store. Heavy use over months can grow to several GB — plan accordingly or use the PostgreSQL backend.
- **Linux or macOS** recommended. **Windows native support (early beta)** landed in v0.14.0 — works on cmd.exe and PowerShell without WSL.

## Step 1 — Install Hermes

```
pip install hermes-agent

# Verify
hermes --version
# hermes/0.14.0 linux-x64 python/3.12.3
```

Hermes also registers in Zed's ACP Registry — Zed users can install it in one click via `uvx` instead. For all other editors and terminals, `pip install hermes-agent` is the canonical path.

Unlike OpenClaw and IronClaw, Hermes installs as both a CLI tool (`hermes`) and a background daemon. The daemon is what maintains persistent memory and scheduled tasks when you're not actively using it.

## Step 2 — Run the Setup Wizard

```
hermes init
```

The wizard asks seven questions:

| Question | Default | Recommendation |
| --- | --- | --- |
| Model provider | — | `anthropic` (Claude has the best long-context handling) |
| API key | — | Paste key — stored encrypted in OS keychain |
| Primary model | `claude-sonnet-4-6` | Accept default, or use `claude-opus-4-6` for complex tasks |
| Memory store type | `sqlite` | Accept `sqlite` for personal use; use `postgres` for team/production |
| Memory store path | `~/.hermes/memory.db` | Accept default, or choose a path on a drive with plenty of space |
| Workspace path | `~/.hermes/workspace/` | Accept default |
| Notification channel | `none` | Set to `telegram` if you want task completion alerts on your phone |

After the wizard, Hermes creates:

```
~/.hermes/
  hermes.json          # main config
  memory.db            # SQLite memory store
  workspace/
    PERSONA.md         # who Hermes is (equivalent of OpenClaw's SOUL.md)
    TASKS.md           # scheduled and active tasks
    REFLECTIONS.md     # self-reflection log (written by Hermes)
    MEMORY.md          # manual memory entries (you write these)
  logs/
    daemon.log         # daemon activity log
    tasks.log          # task execution log
```

## Step 3 — Start the Daemon

```
hermes start

# Output:
# [hermes] daemon v0.14.0 starting
# [hermes] memory store: sqlite (~/.hermes/memory.db) — 0 episodes
# [hermes] indexer: ready
# [hermes] scheduler: ready — 0 tasks queued
# [hermes] daemon running (PID 45821)

# Verify it's running
hermes status
# daemon: running (PID 45821)
# memory: 0 episodes, 0 facts, 0 reflections
# tasks: 0 queued, 0 running, 0 completed
```

The daemon runs in the background and survives terminal closures. To stop it:

```
hermes stop
```

### Run as a System Service (recommended)

```
sudo tee /etc/systemd/system/hermes.service << 'EOF'
[Unit]
Description=Hermes Agent Daemon
After=network.target

[Service]
Type=forking
PIDFile=/home/YOUR_USERNAME/.hermes/daemon.pid
User=YOUR_USERNAME
ExecStart=/usr/local/bin/hermes start
ExecStop=/usr/local/bin/hermes stop
Restart=on-failure
RestartSec=10
EnvironmentFile=/home/YOUR_USERNAME/.hermes/.env

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable hermes
sudo systemctl start hermes
```

## Model Selection for Hermes

Hermes's memory compression means it can work with shorter context windows than you'd expect — the compression layer summarises old episodes before injecting them. But the model's reasoning quality matters more for long-horizon tasks than for quick Q&A. Choose based on task complexity:

| Model | Context | Best for | Approx cost/month (typical Hermes use) |
| --- | --- | --- | --- |
| Claude Haiku 4.5 | 200K | Simple automation: reminders, summaries, light research | $2–6 |
| Claude Sonnet 4.6 | 200K | Most Hermes tasks — good reasoning at a reasonable price | $8–20 |
| Claude Opus 4.6 | 200K | Complex multi-week projects requiring deep reasoning | $30–80 |
| GPT-4.1 | 128K | Good alternative to Sonnet; slightly cheaper per token | $7–18 |
| Grok 4.3 (via SuperGrok OAuth) | 1M | Huge single-context tasks — no API key needed if you have a SuperGrok subscription | Included in SuperGrok plan |
| Gemini 1.5 Pro | 1M | Tasks requiring very large single-context windows (unusual) | $5–15 |
| Local Ollama (Qwen 2.5 14B+) | 32K | Low-stakes background tasks where privacy matters more than quality | $0 (electricity) |

The recommended setup: use Sonnet as the default with Opus as an escalation for tasks Hermes explicitly flags as high-complexity. Configure this in the config:

```
{
  "model": {
    "primary":   "anthropic/claude-sonnet-4-6",
    "heavy":     "anthropic/claude-opus-4-6",
    "light":     "anthropic/claude-haiku-4-5",
    "autoEscalate": {
      "enabled":      true,
      "triggerTokens": 50000,  // escalate to heavy model when task exceeds this
      "triggerScore":  0.8     // or when complexity score exceeds this threshold
    }
  }
}
```

## Step 4 — Your First Task

Give Hermes a task through the CLI:

```
# A simple immediate task
hermes run "Summarise the top 5 AI news stories from this week and save to workspace/weekly-brief.md"

# A scheduled task
hermes run --at "tomorrow 8am" "Check my GitHub notifications and send me a Telegram summary"

# A recurring task
hermes run --every "monday 9am" "Run a weekly project status check and update TASKS.md with blockers"

# A long-horizon task (Hermes breaks it into steps autonomously)
hermes run "Over the next week, research the current state of AI agent frameworks, compare them on 10 dimensions, and produce a 2000-word report. Check in with me at the halfway point."
```

Monitor task progress:

```
hermes tasks list
# ID       STATUS    SCHEDULED     DESCRIPTION
# t-001    running   now           Summarise AI news...
# t-002    queued    2026-04-07    Check GitHub notifications...
# t-003    queued    2026-04-13    Weekly status check (recurring)

hermes tasks log t-001   # see execution log for a task
hermes tasks cancel t-002  # cancel a queued task
```

## Step 5 — Verify Memory Is Working

After your first task completes, Hermes automatically stores an episode in its memory database. Check it:

```
hermes memory status
# Episodes:    1
# Facts:       4
# Reflections: 1
# DB size:     128 KB

hermes memory search "AI news"
# [episode:001] 2026-04-06 — Summarised top 5 AI stories...
# [fact:003] Claude Opus 4.6 released April 2026 with 200K context
```

If memory shows 0 episodes after a completed task, your version is likely below v0.9.3. Upgrade immediately.

## CLI Quick Reference

| Command | What it does |
| --- | --- |
| `hermes init` | First-time setup wizard |
| `hermes start` | Start the background daemon |
| `hermes stop` | Stop the daemon gracefully |
| `hermes status` | Show daemon status, memory counts, task queue |
| `hermes run "..."` | Submit a task for immediate or scheduled execution |
| `hermes run --at "8am tomorrow" "..."` | Schedule a one-time task |
| `hermes run --every "monday 9am" "..."` | Schedule a recurring task |
| `hermes tasks list` | Show all tasks (queued, running, completed) |
| `hermes tasks log ` | Show execution log for a task |
| `hermes tasks cancel ` | Cancel a queued task |
| `hermes memory status` | Show memory store counts and size |
| `hermes memory search "query"` | Search memory episodes and facts |
| `hermes memory compact` | Run manual memory compression (usually automatic) |
| `hermes logs` | Stream daemon log live |
| `hermes config get ` | Read a config value |
| `hermes config set ` | Update config and reload daemon |
| `hermes proxy` | Start a local OpenAI-compatible proxy backed by your OAuth provider (Claude Pro, ChatGPT Pro, SuperGrok) — lets Codex, Aider, Cline hit your subscription without an API key |
| `hermes update` | Update Hermes to the latest version |

## More Hermes Guides

Continue your Hermes journey — every guide on the hub:

 [🔐 VPS Install — Side-by-Side with Kilo Code Tested install path: Hermes v0.11+ and Kilo CLI on one Hetzner Ubuntu 24.04 VPS. Per-user isolation, OpenRouter, no public ports.](https://openclawdatabase.com/hermes/vps-install/)

 [💬 Discord Gateway — The Definitive Setup Five silent failure modes solved. Developer Portal, the systemd linger + bus-socket fix, the auto_thread trap, channel architecture.](https://openclawdatabase.com/hermes/discord-gateway/)

 [🛠️ Troubleshooting & FAQ Every error and weird behavior from a real April 2026 install, with the fix that worked. SSH, install, runtime, Discord, systemd, Kilo, FAQ.](https://openclawdatabase.com/hermes/troubleshooting/)

 [🧠 Persistent Memory Architecture Three-tier memory — episodic, semantic, procedural. SQLite vs PostgreSQL, compression, retrieval tuning.](https://openclawdatabase.com/hermes/memory/)

 [🗓 Long-Running Tasks & Scheduling TASKS.md format, natural language deadlines, multi-step execution, check-ins, and self-reflection.](https://openclawdatabase.com/hermes/tasks/)

 [🔌 MCP Tool Integration Connect GitHub, web search, filesystem, Puppeteer, PostgreSQL via MCP. v0.9 adapter and v1.0 native MCP.](https://openclawdatabase.com/hermes/mcp-tools/)

 [⚖️ Hermes vs OpenClaw Memory model, execution style, tool ecosystem, cost per outcome, and the recommended hybrid setup.](https://openclawdatabase.com/hermes/vs-openclaw/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)

← Back to [Hermes hub](https://openclawdatabase.com/hermes/) · Next: [Persistent Memory Architecture →](https://openclawdatabase.com/hermes/memory/)



================================================================
# Hermes Skills Guide: Write Your Own Self-Improving Skills (2026)
URL: https://openclawdatabase.com/hermes/skills-guide/
Last updated: 2026-06-01
================================================================

# Hermes Skills Guide: Write Your Own

Self-writing skills are Hermes's whole identity. When it solves a hard problem, it writes itself a [skill](https://openclawdatabase.com/glossary/skill/) — a small note describing how to do that job — so the next time you ask, it just does it. Over months, your agent builds a personal library of skills tuned to your work. This guide explains how that loop works and how to drive it safely: describe the outcome, let Hermes draft the skill, test it, review what it can touch, and persist it.

⚠️ Safety first: skills are code that runs with your permissions

A Hermes skill can read files, hit the network, and use your credentials. That's true whether the agent wrote it or you imported it. **Don't install unknown third-party skills.** Security researchers auditing a major public agent-skill registry in early 2026 found a meaningful share of published skills contained credential-exfiltration or reverse-shell code. The safe pattern below has the agent *write* the skill from your description so you can read exactly what it does before enabling it.

## How Hermes skills work

- **A skill is a reusable recipe.** It captures the steps, the tools/[MCP servers](https://openclawdatabase.com/glossary/mcp/) involved, the inputs it expects, and the output it produces — so a multi-step task becomes a single repeatable action.
- **The self-improvement loop.** After Hermes works through a novel task, it can write a skill capturing what worked. Next time the same job appears, it loads the skill instead of re-deriving the solution from scratch — faster, cheaper, and more consistent.
- **Skills compound.** Unlike a one-off chat, a saved skill persists across sessions and restarts. A six-month-old Hermes install has a library shaped by how *you* work — that accumulated context is the real moat, not the base model.
- **Bundles group related skills.** Recent Hermes versions let you load a set of related skills together (a "bundle") in one command, so a whole workflow comes online at once.

## Step-by-step: have your agent write a skill

1. **Describe the outcome, not the code.** Tell Hermes the job to be done and what "done" looks like. Good skill requests are specific about inputs, outputs, and edge cases — and silent about implementation.
2. **Let Hermes draft the skill.** It writes a skill file with the steps and the tools it needs. If it requires an MCP server or a channel you haven't connected, it will say so.
3. **Test on a real example.** Run it against one real input and read the output. Don't trust a skill you've never seen produce a correct result.
4. **Review what it can touch** (see the checklist below) before you let it persist.
5. **Persist it.** Save the reviewed skill so the agent reuses it automatically. From here it's part of your library.
6. **Iterate.** When the skill misses an edge case, describe the gap and let Hermes revise it. Re-review, re-save.

## Copy this prompt

Paste this to have Hermes author a skill the safe way — describe-outcome, draft, test, and stop for your review before persisting:

```
Write me a Hermes skill that does the following job:

  <describe the job: the trigger, the inputs, the steps,
   and exactly what a correct output looks like>

Requirements:
- Use only the tools and MCP servers I already have connected.
  If you need one I don't have, stop and tell me which one and why.
- Request the minimum access needed. List every file path, network
  domain, and secret/credential the skill will touch.
- Do NOT take any irreversible action (sending, deleting, posting,
  paying) without an explicit confirmation step.
- Run it once on this real example: <paste one real input>
- Show me the skill file and the test output, then STOP.
  Do not persist or enable it until I say "save it".
```

## Ready-to-use starter prompts

- **Inbox triage:** "Write a skill that reads my unread email, labels each message as urgent / reply-needed / FYI / ignore, and drafts (not sends) a reply for anything in 'reply-needed'."
- **Daily brief:** "Write a skill that each morning at 8am compiles my calendar, my open tasks, and overnight messages into a single short brief and sends it to my Telegram."
- **Competitor teardown:** "Write a skill that takes a URL, has the browser tool capture the page and the visible tech signals, and produces a one-page summary — no logins, read-only."
- **Release watcher:** "Write a skill that checks a given GitHub repo's releases once a day and messages me a plain-language summary only when there's a new tag."

## After your agent writes the skill: the review checklist

Before you save any skill, read it and confirm:

1. **Filesystem:** which paths does it read or write? A skill that should only read your calendar shouldn't be touching `~/.ssh` or your config directory.
2. **Network:** which domains does it reach? Every outbound domain should map to a step you asked for.
3. **Secrets:** which credentials or env vars does it use? Least privilege — a formatter shouldn't see your API keys.
4. **Irreversible actions:** does anything send, delete, post, or pay *without* a confirmation step? If so, add the gate before saving.
5. **Tool chaining:** does it invoke other skills or MCP servers? Those inherit its reach — review them too.

This is the same allowlist discipline covered in the [Hermes security guide](https://openclawdatabase.com/hermes/security/): only reviewed, version-pinned skills get enabled.

## More Hermes Guides

Build, secure, and connect your agent:

 [⚡ Quick Start — 20 Minutes](https://openclawdatabase.com/hermes/setup/)
 [🔐 Security & Hardening](https://openclawdatabase.com/hermes/security/)
 [🔌 MCP Tool Integration](https://openclawdatabase.com/hermes/mcp-tools/)
 [🧠 Persistent Memory Architecture](https://openclawdatabase.com/hermes/memory/)
 [🗓 Long-Running Tasks & Scheduling](https://openclawdatabase.com/hermes/tasks/)
 [🛠 Compare: OpenClaw Skills Guide](https://openclawdatabase.com/openclaw/skills-guide/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)



================================================================
# Hermes Long-Running Tasks & Scheduling 2026
URL: https://openclawdatabase.com/hermes/tasks/
Last updated: 2026-05-30
================================================================

# Long-Running Tasks & Scheduling — Autonomous Workflows

Hermes's task scheduler is what makes it an agent rather than a chatbot. You give it a goal with a deadline and it works — independently, across restarts, across sleep cycles — until the goal is done or it needs your input. This guide covers task submission, the TASKS.md workspace file, multi-step autonomous execution, check-in patterns, and how to keep long-running tasks safe.

## How the Task Scheduler Works

When you submit a task to Hermes, it goes through four stages:

1. **Planning** — Hermes uses the model to break the task into concrete steps with estimated completion times. The plan is stored in TASKS.md.
2. **Queuing** — Steps are added to the task queue with their scheduled execution times.
3. **Execution** — The daemon picks up each step at its scheduled time, pulls relevant memory context, calls the model, executes any tool calls, and stores results.
4. **Reflection** — After the final step, Hermes writes a reflection to the procedural memory store and REFLECTIONS.md.

Between steps, the daemon is idle — no API calls, no cost. You're only billed for the actual step executions.

## Task Submission — CLI Reference

### Immediate execution

```
hermes run "Summarise this week's GitHub issues in my Atlas project and categorise by priority"
```

### Scheduled once

```
# Natural language scheduling
hermes run --at "tomorrow 7am" "Check server disk usage and send me a Telegram report"
hermes run --at "friday 5pm" "Compile the week's completed GitHub PRs into a changelog entry"
hermes run --at "2026-05-01" "Start the Q2 project review process"

# ISO 8601 timestamp also accepted
hermes run --at "2026-04-07T08:00:00" "Morning brief"
```

### Recurring tasks

```
# Natural language recurrence
hermes run --every "weekday 8am" "Morning brief: pull GitHub notifications and server status"
hermes run --every "monday 9am" "Weekly project status update"
hermes run --every "1st of month 10am" "Monthly cost review across all API providers"

# Cron syntax also accepted
hermes run --every "0 8 * * 1-5" "Weekday morning brief"
```

### Long-horizon tasks with check-ins

```
# Tell Hermes how long it has and when to check in
hermes run \
  --deadline "2026-04-13" \
  --checkin "daily 6pm" \
  "Research the current state of AI agent memory architectures. Read at least 20 sources. Produce a structured comparison report with citations. Check in with me each evening with progress."
```

### Task with explicit steps

```
hermes run --plan "$(cat <<'EOF'
Goal: Migrate my blog from WordPress to a static site

Steps:
1. Export all posts from WordPress (ask me for the export file path)
2. Convert each post to Markdown using pandoc
3. Organise by category into /content/ directory structure
4. Generate index files for each category
5. Write a migration summary report

Check in after each step. Don't proceed to the next step without my approval.
EOF
)"
```

## TASKS.md — The Task Workspace File

Hermes maintains a running TASKS.md in your workspace that shows all active, queued, and recently completed tasks. You can also write tasks directly into this file and Hermes will pick them up on its next scheduler cycle (every 60 seconds by default).

```
# ~/.hermes/workspace/TASKS.md

## Active Tasks

### t-007: Research AI memory architectures
- **Status:** running (step 3 of 8)
- **Deadline:** 2026-04-13
- **Check-in:** daily 6pm
- **Next step:** Summarise sources 11–15 and update comparison matrix
- **Next execution:** 2026-04-06 14:30

## Queued Tasks

### t-008: Weekly project status
- **Schedule:** recurring — monday 9am
- **Next run:** 2026-04-08 09:00
- **Description:** Pull GitHub open issues, check server metrics, send Telegram summary

## Defining Tasks Here (Hermes picks these up automatically)

### New Task (Hermes will plan and schedule this)
- **Description:** Review all open GitHub issues in the Atlas repo and label them by component
- **Deadline:** 2026-04-09
- **Priority:** high
```

When Hermes sees a section without an ID (like "New Task"), it plans it, assigns an ID, and converts it to a proper task entry. This lets you define tasks in your editor without using the CLI.

## Check-Ins — Staying in the Loop

Check-ins are how Hermes communicates progress on long tasks without interrupting you constantly. Configure a notification channel, and Hermes sends a structured update at each check-in time:

```
# Configure Telegram for check-ins (in hermes.json)
{
  "notifications": {
    "channel": "telegram",
    "botToken": "${TELEGRAM_BOT_TOKEN}",
    "chatId":   "YOUR_CHAT_ID",
    "checkIn": {
      "format": "brief"   // brief | detailed | markdown
    }
  }
}
```

A typical check-in message:

```
📋 Hermes Check-In — Research task (t-007)
2026-04-06 18:00

Progress: Step 3/8 complete
✓ Identified 20 relevant sources
✓ Read and summarised sources 1–10
⏳ Currently: Summarising sources 11–15

On track for Friday deadline.
No blockers — continuing autonomously.

Reply to give instructions, or ignore to let me continue.
```

You can reply to a check-in message via Telegram and Hermes will incorporate your instructions before the next step:

```
# Example reply to a check-in:
"Skip the Letta paper — I've already read it. Focus on the MemGPT and Reflexion approaches."
# Hermes stores this as an episode, adjusts the remaining steps, continues
```

## Autonomous Step Execution — What Hermes Does Alone

During autonomous execution, Hermes can:

- Make API calls to configured MCP tools and providers
- Read and write files in the workspace directory
- Search the web via configured search tools
- Run shell commands if granted and if a tool wraps them
- Store intermediate results to memory for use in later steps
- Re-plan remaining steps based on what it discovers

What Hermes will not do autonomously (it pauses and asks):

- Send emails, messages, or make posts — even if a channel is configured
- Delete files or make destructive changes
- Make API calls that cost money beyond the configured step budget
- Proceed with a step it has low confidence in
- Take any action the task description didn't explicitly cover

Define the scope of autonomy explicitly in each task

Hermes respects the scope you give it. "Research and write a report" gives it autonomy to read and write. "Research, write, and publish to my blog" gives it autonomy to publish. Be deliberate — it's better to start with a narrower scope and widen it after testing than to grant full autonomy to an untested task definition.

## Task Safety Controls

### Step budget

Prevent runaway tasks by capping how many model calls a single task can make:

```
{
  "tasks": {
    "defaultStepBudget":  20,   // max model calls per task
    "maxStepBudget":     100,   // hard ceiling even if task requests more
    "onBudgetExhausted": "pause-and-notify"  // pause | fail | notify-and-continue
  }
}
```

### Token budget per step

```
{
  "tasks": {
    "maxTokensPerStep": 8000   // cap input+output tokens for any single step
  }
}
```

### Confidence threshold

Hermes scores its own confidence before executing each step. Below the threshold, it pauses and asks:

```
{
  "tasks": {
    "confidenceThreshold": 0.75  // pause and check in if confidence falls below this
  }
}
```

### Dry-run mode

```
# Plan the task without executing anything
hermes run --dry-run "Migrate blog from WordPress to static site"

# Output: shows the full plan, estimated steps, model calls, and cost estimate
# Nothing is executed or stored
```

## Managing Running Tasks

```
# List all tasks
hermes tasks list
hermes tasks list --status running
hermes tasks list --status queued

# Show full detail for a task
hermes tasks show t-007

# Show execution log
hermes tasks log t-007

# Pause a running task (stops after current step finishes)
hermes tasks pause t-007

# Resume a paused task
hermes tasks resume t-007

# Cancel a task (stops immediately, stores partial results)
hermes tasks cancel t-007

# Retry a failed task from the last successful step
hermes tasks retry t-007

# Add instructions mid-task (injected before next step)
hermes tasks note t-007 "Focus on peer-reviewed sources only from now on"
```

## /goal — Persistent Goals Across Turns (v0.13.0+)

The `/goal` command locks the agent onto a target and keeps it there across turns — the agent won't declare itself done until the goal's success criteria are met. Useful when you want Hermes to keep working without needing to re-prompt it after each step.

```
# Set a persistent goal
/goal Write a complete competitive analysis of the top 5 AI agent frameworks by Friday

# Check current goal
/goal status

# Clear the active goal
/goal clear
```

While a goal is active, Hermes evaluates every completed turn against the criteria before deciding whether to continue or stop. The agent won't drift — it stays focused on the goal even across long multi-step runs.

### /subgoal — Add Criteria Mid-Run (v0.14.0+)

Once a `/goal` is running, `/subgoal` lets you layer in additional success criteria without restarting:

```
# Add extra criteria to the active goal mid-run
/subgoal Include a cost-per-token comparison for each framework
/subgoal Prioritise frameworks with MCP support
```

The judge factors the new criteria into the done-or-keep-going decision on the next turn. No restart, no context loss.

## no_agent Cron Mode — Script-Only Watchdogs (v0.13.0+)

Cron jobs can now skip the agent entirely and just run a shell script. Empty stdout is silent; non-empty output gets delivered verbatim to your notification channel. Ideal for simple monitoring tasks where you don't need LLM reasoning:

```
# hermes.json — cron job with no_agent mode
{
  "cron": {
    "jobs": [
      {
        "id": "disk-check",
        "schedule": "*/30 * * * *",
        "no_agent": true,
        "script": "df -h | awk '$5 > 80 {print \"WARN: \" $0}'"
      },
      {
        "id": "uptime-ping",
        "schedule": "0 * * * *",
        "no_agent": true,
        "script": "curl -sf https://mysite.example.com || echo 'ALERT: site down'"
      }
    ]
  }
}
```

`no_agent` jobs cost nothing — no model call, just a shell script. Use them for polling, health checks, and alerting that don't need intelligence.

## Sessions Survive Restarts (v0.13.0+)

Before v0.13.0, a gateway restart mid-task would lose the in-flight session. As of v0.13.0, the gateway auto-resumes interrupted sessions when it comes back up — whether from a crash, a `hermes update`, or a deliberate restart. No task context is lost.

This makes it safe to run `hermes update` even while tasks are in progress. The daemon will restart, re-attach to the session, and continue from where it left off.

## Self-Reflection After Tasks

When a task completes, Hermes automatically runs a reflection pass. The reflection is stored in both REFLECTIONS.md and the procedural memory store. You can read them:

```
cat ~/.hermes/workspace/REFLECTIONS.md

# Example reflection entry:
---
Task: Research AI memory architectures (t-007)
Completed: 2026-04-13
Duration: 7 days, 12 steps

What went well:
- Breaking research into daily reading quotas kept the task on track
- Using a comparison matrix from step 2 made the final report much easier to write

What to improve:
- Should have confirmed source quality criteria with user before starting
- Step 5 (synthesising conflicting claims) needed more time than allocated

Learned patterns:
- For research tasks: always establish evaluation criteria in step 1
- For report tasks: draft the structure in step 1, fill it in over subsequent steps
- User prefers sources from 2024 onwards; ignore older papers unless foundational
```

These reflections are retrieved automatically for future similar tasks — Hermes genuinely improves with experience.

## More Hermes Guides

Continue your Hermes journey — every guide on the hub:

 [⚡ Quick Start — 20 Minutes Install Hermes, run the setup wizard, start the daemon, pick a model, submit your first scheduled task.](https://openclawdatabase.com/hermes/setup/)

 [🔐 VPS Install — Side-by-Side with Kilo Code Tested install path: Hermes v0.11+ and Kilo CLI on one Hetzner Ubuntu 24.04 VPS. Per-user isolation, OpenRouter, no public ports.](https://openclawdatabase.com/hermes/vps-install/)

 [💬 Discord Gateway — The Definitive Setup Five silent failure modes solved. Developer Portal, the systemd linger + bus-socket fix, the auto_thread trap, channel architecture.](https://openclawdatabase.com/hermes/discord-gateway/)

 [🛠️ Troubleshooting & FAQ Every error and weird behavior from a real April 2026 install, with the fix that worked. SSH, install, runtime, Discord, systemd, Kilo, FAQ.](https://openclawdatabase.com/hermes/troubleshooting/)

 [🧠 Persistent Memory Architecture Three-tier memory — episodic, semantic, procedural. SQLite vs PostgreSQL, compression, retrieval tuning.](https://openclawdatabase.com/hermes/memory/)

 [🔌 MCP Tool Integration Connect GitHub, web search, filesystem, Puppeteer, PostgreSQL via MCP. v0.9 adapter and v1.0 native MCP.](https://openclawdatabase.com/hermes/mcp-tools/)

 [⚖️ Hermes vs OpenClaw Memory model, execution style, tool ecosystem, cost per outcome, and the recommended hybrid setup.](https://openclawdatabase.com/hermes/vs-openclaw/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)

← Back to [Hermes hub](https://openclawdatabase.com/hermes/) · See also: [Persistent Memory Architecture](https://openclawdatabase.com/hermes/memory/) · [MCP Tool Integration](https://openclawdatabase.com/hermes/mcp-tools/)



================================================================
# Hermes Telegram Setup Guide 2026 — Bot, Allowlist, Groups
URL: https://openclawdatabase.com/hermes/telegram/
Last updated: 2026-06-01
================================================================

# Hermes Channel Setup: Telegram

Telegram is the fastest way to put Hermes in your pocket: create a bot, paste a token, lock it to your account, and you can delegate to your agent from anywhere while it works on a server back home. This guide covers the five-minute setup and — just as importantly — the allowlist that keeps strangers out.

## 1. Create a bot with BotFather

1. In Telegram, search for **@BotFather** (the official bot, blue checkmark) and start a chat.
2. Send `/newbot`. Choose a display name (e.g. "My Hermes") and a username ending in `bot` (e.g. `my_hermes_bot`).
3. BotFather replies with an **HTTP API token** that looks like `123456789:ABCdefGhIJKlmNoPQRstuVWxyz`. Treat it like a password.

## 2. Wire the token into Hermes

Store the token in your secrets manager or an environment variable — **not** in a config file committed to git — and point the Telegram channel at it. In the Hermes config the Telegram channel needs the bot token and the allowlist (next step). After saving, restart the daemon so it picks up the new channel.

Keep the token out of chat and git

Anyone with the bot token can impersonate your bot. Store it in env/secrets, rotate it (BotFather → `/revoke`) if it ever leaks, and never paste it into a channel the agent reads. See the [security guide](https://openclawdatabase.com/hermes/security/) for key hygiene.

## 3. Lock it down with an allowlist

A fresh bot will talk to *anyone* who finds it. Fix that before doing anything real:

1. Get your numeric Telegram user ID: message **@userinfobot**, which replies with your ID.
2. Add that ID to the Telegram channel's **allowlist** in the Hermes config. Hermes silently drops messages from any account not on the list.
3. Restart and confirm: message the bot from your account (it replies), then have a friend message it (it ignores them).

## 4. Running in a group

- **Add the bot to the group** and, if it needs to read all messages (not just commands), disable privacy mode in BotFather (`/setprivacy` → Disable).
- **Run mention-only.** Configure the agent to respond only when explicitly mentioned, so it doesn't reply to every message or leak data to the whole group on a stray trigger.
- **Keep the allowlist on.** Only approved members should be able to issue commands, even inside a trusted group.

## Troubleshooting

- **Bot doesn't reply:** confirm the daemon is running, the token is correct, and your user ID is on the allowlist (the most common cause of silent non-replies).
- **Replies in DM but not group:** privacy mode is on — disable it in BotFather, or address the bot with its @username.
- **Replies to everyone in a group:** mention-only isn't enabled — turn it on so it only answers when tagged.

More fixes in the [Hermes troubleshooting guide](https://openclawdatabase.com/hermes/troubleshooting/).

## More Hermes Guides

Connect more channels and secure your agent:

 [💬 Channel Setup: Discord](https://openclawdatabase.com/hermes/discord-gateway/)
 [🔐 Security & Hardening](https://openclawdatabase.com/hermes/security/)
 [📊 Web Dashboard](https://openclawdatabase.com/hermes/dashboard/)
 [⚡ Quick Start — 20 Minutes](https://openclawdatabase.com/hermes/setup/)
 [🗓 Long-Running Tasks](https://openclawdatabase.com/hermes/tasks/)
 [✈️ Compare: OpenClaw Telegram](https://openclawdatabase.com/openclaw/telegram/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)



================================================================
# Hermes + Kilo Code Troubleshooting & FAQ (2026)
URL: https://openclawdatabase.com/hermes/troubleshooting/
Last updated: 2026-05-30
================================================================

# Hermes Agent + Kilo Code — Troubleshooting & FAQ

A flat list of every weird thing we hit while installing Hermes Agent v0.11 and Kilo Code CLI side-by-side on a Hetzner Ubuntu 24.04 VPS in April 2026, with the fix that actually worked. Search by symptom.

First two places to check

If your problem isn't here, the next two best places are `journalctl --user -u hermes-gateway -n 200 --no-pager` (Hermes) and the Kilo CLI's own `--help` output. Both agents log generously when something fails.

## Server / SSH issues

### "I clicked Console in the Hetzner dashboard and it just says `login:`"

The web console is a real virtual terminal — it has no idea who you are. At the `login:` prompt it expects a Linux username (`root`) and a password. If you only added an SSH key during server creation and never set a root password, root has no password and the web console cannot let you in until you set one.

**Fix:** SSH in via PowerShell using your key, then run `passwd` to set a root password. Write it down offline. Use only via the web console as a recovery channel.

### "`ssh root@ip` says Permission denied (publickey)"

The SSH key your local machine is presenting is not the one Hetzner has on file. Compare:

```
cat $HOME\.ssh\id_ed25519.pub
```

against Hetzner Cloud → Security → SSH Keys. If your local key isn't listed, either add it to Hetzner (and rebuild the server, or paste it manually after recovering via the web console) or reset the root password from Hetzner and access via the web console.

### "ssh times out / connection refused"

Three usual causes:

1. The Hetzner Cloud Firewall is denying inbound 22. Check Cloud → Firewalls.
2. UFW on the server is denying 22 (only relevant if it was enabled before allowing 22 — see "I locked myself out" below).
3. The server is rebooting. Wait 60 seconds.

### "I'm locked out — UFW or sshd config broke me"

The Hetzner web console is your escape hatch. Log in there with the root password you set in `passwd`. Then either fix the offending file or `ufw disable`. SSH should come back immediately.

If you never set a root password, this is why we keep harping on Phase 1.1 of the [VPS install guide](https://openclawdatabase.com/hermes/vps-install/).

### "My SSH session keeps timing out mid-task"

By default Ubuntu's sshd does not send keepalives. Add to `/etc/ssh/sshd_config`:

```
ClientAliveInterval 60
ClientAliveCountMax 10080
```

And to `~/.ssh/config` on your local machine:

```
Host hetzner
    ServerAliveInterval 60
    ServerAliveCountMax 10080
```

Then run agent jobs inside `tmux` so even an actual disconnect doesn't kill them.

### "Connection reset" / `client_loop: send disconnect`

Almost always a network-level interruption (your wifi, a NAT gateway). Reconnect. If frequent, install `mosh` as a more disconnection-tolerant alternative to SSH. `tmux` + keepalives usually solves it.

## User-isolation issues

### "I switched to the hermes user and `apt install` does not work"

By design. The hermes user has no sudo. Anything system-wide must be run from a separate root SSH window. The two-window pattern (one for root, one for the agent user) is normal and good.

### "I want hermes to be able to install packages"

You don't, actually. Giving an autonomous agent sudo defeats the entire isolation model. If a specific binary is genuinely missing, install it as root once and everyone uses it. The system Python, Node, ripgrep, ffmpeg, and tmux cover 95% of what either agent needs.

If you really need a per-user system-package install, look at `nix` (user-mode Nix), `pkgsrc`, or `linuxbrew` — none require root and all work fine in a user's home directory.

## Hermes install issues

### "The installer asks *Install build tools? [Y/n]* and I'm running as hermes (no sudo)"

Answer **n**. The `build-essential` package is already installed system-wide if you followed Phase 3. Almost no Python packages will need to compile — they ship pre-built wheels for linux/amd64. Hermes will install correctly.

### "Playwright is asking for sudo password"

Press **Ctrl+C** to abort that step. The Hermes Python install completes without it. Then, in a second window as root:

```
/home/hermes/.hermes/hermes-agent/node_modules/.bin/playwright install-deps chromium
```

That's the same Playwright the installer dropped, but executed as root, which lets it apt-install the Chromium system libraries (libnss3, libxkbcommon0, etc.). Takes 30–60 seconds.

### "After install, hermes is not on PATH (`Command 'hermes' not found`)"

The installer modifies `~/.bashrc` to source `~/.local/bin/env`, but if you Ctrl+C'd during Playwright the install may not have symlinked the binary into `~/.local/bin/`. Fix:

```
ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes ~/.local/bin/hermes
which hermes
hermes --version
```

### "Where is my installation?"

```
/home/hermes/.hermes/                    # Hermes' home
├── hermes-agent/                        # The repo
│   ├── venv/bin/hermes                  # The actual binary
│   ├── node_modules/.bin/playwright     # Playwright (Node-based)
│   └── ...
├── .env                                 # Secrets file (mode 600)
└── config.yaml                          # Behavior config
```

The user-level systemd unit lives at `~/.config/systemd/user/hermes-gateway.service`.

## Hermes runtime issues

### "I run `hermes` and it doesn't start any wizard, just says `[Y/n]` to launch chat"

Setup already ran (probably during install). To re-run the wizard:

```
hermes setup           # full
hermes setup model     # only LLM
hermes setup gateway   # only messaging
hermes config          # view current settings
hermes config edit     # open config in editor
```

### "401 Unauthorized" from OpenRouter

The API key is wrong, expired, or deleted. Check `grep OPENROUTER ~/.hermes/.env`. Replace if stale. Restart the gateway: `systemctl --user restart hermes-gateway`.

### "402 Payment Required"

Your OpenRouter account has zero credit. Add at least $5–10 (this also raises the free-tier rate limit from ~200/day to ~1000/day). The agent will then fall back to a paid model when free-tier is rate-limited, which is usually what you want.

### "429 Too Many Requests" from OpenRouter

You've hit the free-tier daily cap (~200/day unfunded, ~1000/day funded). Either wait until UTC midnight or switch the default model to a paid one. In `hermes setup model`, pick `anthropic/claude-sonnet-4-6` or similar.

### "Hermes is responding really slowly"

Free-tier models on OpenRouter can take 30–90 seconds for the first call after a cold start. Subsequent calls are faster. Models that ship with `:free` suffix are also routed to whichever provider has free capacity — quality and latency vary per call.

If consistent slowness is a problem, switch to a paid model. `anthropic/claude-sonnet-4-6` or `openai/gpt-5` will be 2–5 seconds per turn.

### "ESM updates can be applied" message every login

These are extra Ubuntu Pro security backports. Free for personal use; not required. Either subscribe with `pro attach` or ignore the message — `unattended-upgrades` is already handling normal security updates.

## Discord gateway issues

For the comprehensive Discord guide, see [Hermes Discord Gateway — The Definitive Setup](https://openclawdatabase.com/hermes/discord-gateway/). The most common failures, distilled:

### "Failed to connect to bus: No medium found"

User systemd is not running for the hermes user, and `XDG_RUNTIME_DIR` is unset. Fix:

```
# As root:
loginctl enable-linger hermes

# As hermes:
export XDG_RUNTIME_DIR=/run/user/$UID
echo 'export XDG_RUNTIME_DIR=/run/user/$UID' >> ~/.bashrc
```

### "Bot is online but reacts with checkmark and never sends words"

You hit the `auto_thread` trap. Edit `~/.hermes/config.yaml`:

```
discord:
  auto_thread: false
```

Restart the gateway.

### "Bot replies in `#general` but not in `#news-home`"

Channel-specific permission override. Either fix permissions on the channel (gear icon → Permissions → bot's role → green-check View/Send/Read/Embed) or delete and recreate the channel.

### "Slash command sync timed out after 30s"

Benign on first start. The bot still works for @mentions and DMs. If slash commands are missing after a few minutes, restart the gateway once.

### "Anyone in any server can talk to my bot"

`DISCORD_ALLOWED_USERS` is empty in your `.env`. Add your numeric Discord user ID (Settings → Advanced → Developer Mode → right-click yourself → Copy User ID). Restart the gateway.

### "I asked the bot which channels it can see and it gave a generic answer"

The LLM is hallucinating — it has no introspective view of the Discord gateway. To know what's configured, do not ask the bot in chat. Inspect the actual files:

```
grep -E '^DISCORD' /home/hermes/.hermes/.env
cat /home/hermes/.hermes/config.yaml | grep -A 20 discord
```

That's ground truth.

## systemd / linger / service issues

### "Service starts then dies one second later (status=1/FAILURE)"

Check the journal for the actual error: `journalctl --user -u hermes-gateway -n 100 --no-pager`. Most common causes:

- Two gateway processes fighting for the same Discord token. Discord allows only one connection per token. Check `ps aux | grep hermes`.
- Bad token or disabled Message Content Intent — login fails, gateway exits.
- Out of memory on a 4 GB box if you also have a heavy build running. Check with `free -h`.

### "Service won't auto-start on boot"

```
loginctl show-user hermes | grep Linger    # must be: Linger=yes
systemctl --user is-enabled hermes-gateway # must be: enabled
```

If lingering is off, the service stops the moment you log out. Run `loginctl enable-linger hermes` as root.

### "I want to see incoming Discord messages in the logs"

Default log level is WARNING. Edit `~/.hermes/config.yaml` and bump the relevant logger to `INFO` or `DEBUG`. Restart. The log will become much chattier.

## Kilo Code issues

### "`npm i -g` fails with EACCES / permission denied"

The npm prefix isn't set. As the kilo user:

```
mkdir -p ~/.npm-global
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm i -g @kilocode/cli
```

This installs to `~/.npm-global/`, no sudo required.

### "`kilo: command not found` after install"

Same fix as Hermes — PATH is not picking up `~/.npm-global/bin`. Ensure that line is in `.bashrc`, then `source ~/.bashrc` or log out and back in.

### "Kilo asks me which model to use every time I run it"

It hasn't saved a default. Inside Kilo: pick a model, then look for a "set as default" option. Or set via env file:

```
echo 'OPENROUTER_MODEL=anthropic/claude-sonnet-4-6' >> ~/.config/kilo/env
```

### "How do I run Kilo non-interactively?"

```
kilo run "your task here"
```

This is the CI-friendly mode — single shot, exits when done. Useful inside scripts or scheduled jobs.

## Operational FAQ

### "How do I rotate my OpenRouter key?"

1. OpenRouter dashboard → Keys → create a new key.
2. Edit `/home/hermes/.hermes/.env` (and `/home/kilo/.config/kilo/env`) — replace `OPENROUTER_API_KEY=`.
3. Restart relevant services (`systemctl --user restart hermes-gateway`).
4. OpenRouter dashboard → revoke the old key.

Total downtime: about 5 seconds per agent.

### "How do I rotate the Discord bot token?"

1. Discord Developer Portal → your app → Bot → **Reset Token**. Copy the new one.
2. Edit `/home/hermes/.hermes/.env` — replace `DISCORD_BOT_TOKEN=`.
3. `systemctl --user restart hermes-gateway`.

The old token is invalidated immediately by Discord on reset.

### "How do I monitor what the agent is actually doing?"

```
# Live log tail
journalctl --user -u hermes-gateway -f

# What files has the agent touched lately?
find /home/hermes/projects -mtime -1 -type f

# OpenRouter spend
# Check the OpenRouter dashboard — the agent's API key shows daily spend
```

### "Can the two agents see each other?"

No. That's the whole point of Phase 2. Verify any time:

```
sudo -u kilo ls /home/hermes 2>&1     # must say Permission denied
sudo -u hermes ls /home/kilo 2>&1     # must say Permission denied
```

### "What if the agent does something destructive in its own home directory?"

Worst case: the agent corrupts or wipes everything in `/home//`. To recover:

```
deluser --remove-home hermes
adduser --disabled-password --gecos "" hermes
chmod 700 /home/hermes
# Then re-run Phase 4 (Hermes install) for that user
```

Total time: ~15 minutes. Keep a copy of `.env` (off-server) so you don't have to regenerate API keys.

### "How do I back up my agent's work?"

The agent's project files are under `/home//projects/`. The simplest backup:

```
sudo tar czf /root/backup-hermes-$(date +%Y%m%d).tar.gz /home/hermes/projects
```

Better: have the agent push to a private GitHub repo (`git push` from inside its project, with credentials in `~/.netrc` mode 600). That gives you both backup and version history.

### "Can I run more than two agents on this box?"

On a 4 GB CX23, two is the practical limit if both run heavy builds simultaneously. For each additional agent:

1. New Linux user (`adduser`, `chmod 700`).
2. `loginctl enable-linger `.
3. Re-do Phase 4 / Phase 6 under that user with that agent's installer.

Watch RAM with `free -h` while both run. If you hit swap thrashing, upgrade the VPS to CPX22 (8 GB) — Hetzner upgrades are zero-downtime.

### "How do I know which version I have?"

```
sudo -u hermes /home/hermes/.local/bin/hermes --version
sudo -u kilo bash -lc 'kilo --version'
```

Hermes prints version, build date, project path, Python version, and OpenAI SDK version, plus an "Up to date" flag if it's current. Kilo prints just version.

## When all else fails

1. **Read the journal.** `journalctl --user -u hermes-gateway -n 200 --no-pager` is right almost every time.
2. **Restart the service.** Half of all "weird" issues clear with `systemctl --user restart hermes-gateway`.
3. **Reboot the VPS.** Effective; embarrassing; works.
4. **Rebuild the user.** `deluser --remove-home `, then redo install. 15 minutes.
5. **File an issue on the project's GitHub:** `NousResearch/hermes-agent` for Hermes, `Kilo-Org/kilocode` for Kilo. Include `--version`, the journal output, and exact reproduction steps.

Project versions verified for this guide: Hermes Agent v0.11.0 (release v2026.4.23), Kilo Code CLI v7.2.x, Ubuntu 24.04.4 LTS, kernel 6.8.0-110, Node 20.20.2, Python 3.12.3.

## More Hermes Guides

Continue your Hermes journey — every guide on the hub:

 [⚡ Quick Start — 20 Minutes Install Hermes, run the setup wizard, start the daemon, pick a model, submit your first scheduled task.](https://openclawdatabase.com/hermes/setup/)

 [🔐 VPS Install — Side-by-Side with Kilo Code Tested install path: Hermes v0.11+ and Kilo CLI on one Hetzner Ubuntu 24.04 VPS. Per-user isolation, OpenRouter, no public ports.](https://openclawdatabase.com/hermes/vps-install/)

 [💬 Discord Gateway — The Definitive Setup Five silent failure modes solved. Developer Portal, the systemd linger + bus-socket fix, the auto_thread trap, channel architecture.](https://openclawdatabase.com/hermes/discord-gateway/)

 [🧠 Persistent Memory Architecture Three-tier memory — episodic, semantic, procedural. SQLite vs PostgreSQL, compression, retrieval tuning.](https://openclawdatabase.com/hermes/memory/)

 [🗓 Long-Running Tasks & Scheduling TASKS.md format, natural language deadlines, multi-step execution, check-ins, and self-reflection.](https://openclawdatabase.com/hermes/tasks/)

 [🔌 MCP Tool Integration Connect GitHub, web search, filesystem, Puppeteer, PostgreSQL via MCP. v0.9 adapter and v1.0 native MCP.](https://openclawdatabase.com/hermes/mcp-tools/)

 [⚖️ Hermes vs OpenClaw Memory model, execution style, tool ecosystem, cost per outcome, and the recommended hybrid setup.](https://openclawdatabase.com/hermes/vs-openclaw/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)

← Back to [Hermes hub](https://openclawdatabase.com/hermes/) · Previous: [Discord Gateway](https://openclawdatabase.com/hermes/discord-gateway/) · See also: [Cross-platform Troubleshooting](https://openclawdatabase.com/troubleshooting/)



================================================================
# Hermes + Kilo Code on a Hetzner VPS — Security-First Install (2026)
URL: https://openclawdatabase.com/hermes/vps-install/
Last updated: 2026-05-30
================================================================

# Hermes + Kilo Code on a Hetzner VPS — Security-First Side-by-Side Install

The actually-tested install path for putting **Hermes Agent** (Nous Research) and **Kilo Code CLI** on the same modest VPS, isolated from each other, both pointed at OpenRouter. This is the version of this guide we wished we'd had on day one — every gotcha we hit during the install is documented inline.

What you are building

- **One Hetzner CX23 VPS** (2 vCPU / 4 GB RAM / 40 GB disk, ~€4.49/month) running Ubuntu 24.04 LTS
- **Two Linux user accounts**, `hermes` and `kilo`, each running its own coding agent. Neither has `sudo`. Neither can read the other's home directory.
- **Hermes Agent** running as a per-user systemd service, listening to a private Discord bot, with persistent memory across sessions
- **Kilo Code CLI** invoked from the terminal (or driven by an editor over SSH)
- **OpenRouter** as the LLM provider for both — free-tier or paid, configurable per agent
- **Zero new public ports**. Only SSH (port 22) is exposed

If you only want one of these agents, stop after the relevant phase. The phases stack cleanly.

## Why this architecture

A coding agent that writes files, runs scripts, and calls a model on your behalf is a powerful tool with a non-zero risk profile. The architecture below makes the blast radius of "the agent does something weird" as small as possible:

- **Per-user isolation.** Every agent runs as its own Linux user with mode 700 on its home directory. If Hermes goes off the rails, it cannot touch Kilo's files or vice versa. If either goes really off the rails, it cannot touch system files at all (no sudo).
- **No sudo for agents.** Both agents install entirely under their own home directories using user-scoped npm prefixes and Python virtualenvs.
- **No new public ports.** All agent control is outbound (Discord, OpenRouter) or via SSH. No code-server, no public web UI.
- **Defense-in-depth firewall.** Hetzner Cloud Firewall at the network edge plus UFW on the OS, both default-deny.
- **Key-only SSH plus fail2ban plus unattended security updates.**
- **Backup root password set** so the Hetzner web console is always usable as a recovery channel if SSH ever breaks.

If your threat model is higher than ours, layer on AppArmor profiles, full-disk encryption, and a separate jump box. The setup below is the floor, not the ceiling.

## Prerequisites

- **A Hetzner Cloud account and a CX23 (or larger) server** running Ubuntu 24.04 LTS. Dashboard at [console.hetzner.cloud](https://console.hetzner.cloud).
- **A Hetzner Cloud Firewall attached to the server**, allowing inbound TCP 22 only. (Cloud → Firewalls → Create.)
- **An SSH key pair on your local machine.** Windows PowerShell ships with `ssh-keygen`. Register the public key in Hetzner before server creation, or via the web console after.
- **An OpenRouter account with a few dollars of credit.** Free tier is rate-limited to ~200 requests/day on unfunded accounts; depositing $10 raises the cap to ~1000/day, which is what an agent actually needs.
- **A Discord account** if you want to drive Hermes from chat (optional — Hermes also works from the CLI).

You do not need a domain name. Everything works IP-only. If you later want HTTPS or public APIs, layer Caddy/Cloudflare in front (out of scope here).

## Phase 1 — Server hardening

Connect via PowerShell (better paste support than the Hetzner web console; keep the web console open in a tab as a recovery channel):

```
ssh root@YOUR.SERVER.IP
```

Accept the host key fingerprint on first connect (`yes`). You'll land at a `root@host:~#` prompt.

### 1.1 Set a backup root password

The Hetzner web console asks for a username and password every time. If you only added an SSH key during server creation, root has no password and the web console is unusable until you set one:

```
passwd
```

Type a strong password (no characters appear as you type — that's normal, not a frozen terminal). Confirm it. **Write the password down somewhere offline.** You'll only use it when SSH is broken.

### 1.2 Update everything and install the security baseline

```
apt update && apt upgrade -y
apt autoremove -y
apt install -y unattended-upgrades fail2ban needrestart curl ca-certificates gnupg
```

If the upgrade pulls a new kernel (likely on a fresh image), `needrestart` warns about a pending reboot. We reboot at the end of the phase. If a `dpkg` prompt asks about `sshd_config`, choose **keep the local version currently installed** unless you know otherwise.

### 1.3 Enable automatic security updates

```
dpkg-reconfigure --priority=low unattended-upgrades
```

A blue dialog appears. Choose **Yes**. From this point Ubuntu will install security updates automatically.

### 1.4 Confirm fail2ban is protecting SSH

```
systemctl enable --now fail2ban
fail2ban-client status sshd
```

A fresh server will already show several banned IPs within minutes. That's normal background internet noise — it confirms the protection is working.

### 1.5 Enable UFW (defense in depth)

The Hetzner Cloud Firewall stops traffic at the network edge. UFW stops anything that gets through at the OS level. Two layers, default-deny:

```
ufw allow 22/tcp
ufw default deny incoming
ufw default allow outgoing
ufw enable
```

When `ufw enable` warns about disrupting existing SSH connections, type `y`. Your session won't drop because we explicitly allowed 22 first. Verify:

```
ufw status verbose
```

Expect: `Status: active`, default `deny (incoming)`, `allow (outgoing)`, with `22/tcp` allowed both v4 and v6.

### 1.6 Harden SSH

Disable password authentication so brute-forcers can't succeed even if they pass fail2ban:

```
sed -i 's/^#\?PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
sed -i 's/^#\?PermitRootLogin.*/PermitRootLogin prohibit-password/' /etc/ssh/sshd_config
sshd -t && systemctl reload ssh && echo "SSH reloaded OK"
```

The final line must print `SSH reloaded OK`. If `sshd -t` reports a syntax error, **do not reboot, do not close the SSH session.** Fix the file in place. The Hetzner web console (with the password from 1.1) is your fallback.

### 1.7 Stop SSH from timing out on long agent runs

Agents can run for tens of minutes between visible output. Without keepalives, your connection drops mid-job. Configure both ends.

**Server side** — append to `/etc/ssh/sshd_config`:

```
echo -e "\n# Keep idle SSH sessions alive\nClientAliveInterval 60\nClientAliveCountMax 10080" >> /etc/ssh/sshd_config
sshd -t && systemctl reload ssh && echo "SSH keepalive on"
```

The 10080 is minutes — about a week of idle tolerance.

**Client side** — on your local Windows machine, in PowerShell, edit (or create) `$HOME\.ssh\config`:

```
Host hetzner
    HostName YOUR.SERVER.IP
    User root
    ServerAliveInterval 60
    ServerAliveCountMax 10080
```

After saving, you can connect with `ssh hetzner` instead of typing the IP every time.

### 1.8 Reboot to load the new kernel

```
reboot
```

SSH drops. Wait 45–60 seconds, reconnect, verify:

```
uname -r        # newer kernel
ufw status      # still active
fail2ban-client status sshd
```

**Phase 1 complete.**

## Phase 2 — Isolated agent users

Each agent gets its own Linux user with a mode-700 home directory and no sudo. They share system Node and Python but nothing user-writable.

```
adduser --disabled-password --gecos "" hermes
adduser --disabled-password --gecos "" kilo
chmod 700 /home/hermes /home/kilo
```

`--disabled-password` means there is no password; the only way into these accounts is `sudo -iu hermes` from root. The agents are never directly reachable from the public internet.

Verify isolation:

```
ls -ld /home/hermes /home/kilo
sudo -u kilo ls /home/hermes 2>&1
sudo -u hermes ls /home/kilo 2>&1
```

Both home directories should show `drwx------`. Both cross-user `ls` calls must print `Permission denied`. **That denial is the security guarantee** — even with full code execution as kilo, code cannot touch hermes's files.

## Phase 3 — Shared dependencies

Installed once at the system level. Both agent users will use them.

```
apt install -y git build-essential python3.12 python3.12-venv python3-pip ripgrep ffmpeg tmux
```

`build-essential` is required up front because the Hermes installer will try to install build tools via `sudo` (which fails for a sudoless user). You want to be able to say "no" to that prompt and have the build still succeed.

Add Node.js 20 LTS (Kilo CLI requires Node ≥ 18; we use 20 LTS):

```
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
node -v && npm -v
```

Verify:

```
node -v             # v20.x.x
npm -v              # 10.x or 11.x
python3.12 --version
git --version
rg --version | head -1
ffmpeg -version | head -1
```

## Phase 4 — Install Hermes Agent (as the hermes user)

Drop into the hermes user:

```
sudo -iu hermes
whoami        # hermes
pwd           # /home/hermes
```

### 4.1 Run the official installer

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

The installer clones the hermes-agent repo into `~/.hermes/hermes-agent/`, creates a Python 3.11 virtualenv via `uv`, and installs dependencies. It will hit two points where the lack of sudo matters:

- **Prompt: "Install build tools? [Y/n]"** — answer **n**. The system already has `build-essential`. Hermes installs fine without sudo.
- **Playwright tries to install browser system libraries via sudo** — when it asks for the hermes user's (nonexistent) password, press **Ctrl+C** to abort that step. Hermes Python install completes. Finish Playwright separately as root, below.

### 4.2 Finish Playwright system libraries (in a second SSH window as root)

Open a second PowerShell window and SSH in as root, leaving your hermes session intact:

```
ssh hetzner   # or ssh root@YOUR.SERVER.IP
```

Then:

```
/home/hermes/.hermes/hermes-agent/node_modules/.bin/playwright install-deps chromium
```

This invokes the Node-based Playwright that the Hermes installer dropped, and lets it install Chromium-required system packages with root's permissions. About 30–60 seconds of `apt install` output.

### 4.3 Symlink the hermes binary if the installer was interrupted

If you Ctrl+C'd during Playwright, the installer may not have finished its PATH wiring. Back in your hermes window:

```
source ~/.bashrc
which hermes
```

If you see `Command 'hermes' not found`, the binary exists but is not yet on PATH:

```
ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes ~/.local/bin/hermes
which hermes
hermes --version
```

You should now see something like:

```
Hermes Agent v0.11.0 (2026.4.23)
Project: /home/hermes/.hermes/hermes-agent
Python: 3.11.15
```

## Phase 5 — Configure OpenRouter and the Hermes Discord gateway

This is the highest-friction part of the entire install. The deeper guide is at [Discord Gateway: Setup, Troubleshooting & Channel Architecture](https://openclawdatabase.com/hermes/discord-gateway/). Summary here is enough to get you live.

### 5.1 Quick-setup the LLM provider

```
hermes setup
```

Choose **Quick setup**. When prompted:

- **Provider:** `openrouter`
- **API key:** paste your `sk-or-v1-...` key (right-click in PowerShell to paste; key is hidden as you type, like a password)
- **Default model:** for free, use `qwen/qwen3-coder-480b:free` (best free agentic-coding model in April 2026), `nvidia/nemotron-3-super-120b:free`, or `deepseek/deepseek-r1:free`. For paid, `anthropic/claude-sonnet-4-6` is the strongest single pick.

When the wizard finishes, answer **n** to "Launch hermes chat now?" — we still have the gateway to set up.

### 5.2 Add OpenRouter spend cap (recommended)

In OpenRouter dashboard → Settings, set a daily or monthly spend cap. This is your hard ceiling against an agent loop running away. Free models do not draw against the cap, but the cap raises your free-model rate limit when funded.

### 5.3 Set up the Discord gateway

```
hermes setup gateway
```

Toggle Discord with **Spacebar** (the wizard uses Space to select; Enter alone with no selection saves "no platforms"). Confirm with Enter. Paste your Discord bot token and your numeric Discord user ID when prompted. Skip the home channel for now.

For full Discord-side configuration (creating the bot in the Developer Portal, getting the token, the required intents, the `auto_thread: false` setting that fixes silent-failures, channel architecture, the systemd service install, lingering, and the `XDG_RUNTIME_DIR` fix) — read [Discord Gateway: Setup, Troubleshooting & Channel Architecture](https://openclawdatabase.com/hermes/discord-gateway/). Skipping any of those steps is the fastest way to a non-functioning bot.

### 5.4 Verify

After gateway install + linger + service start (covered in the gateway guide), the bot should appear green in your Discord member list. Send `@your-bot ping` in any channel and confirm a reply within 30–60 seconds (free models are slow; this is normal).

## Phase 6 — Install Kilo Code CLI (as the kilo user)

Exit the hermes session. From root, drop into the kilo user:

```
sudo -iu kilo
```

### 6.1 Configure a per-user npm prefix

This is what lets us install Kilo CLI globally **without sudo** — `npm i -g` writes to `~/.npm-global/` instead of `/usr/lib/node_modules/`:

```
mkdir -p ~/.npm-global
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
echo 'export XDG_RUNTIME_DIR=/run/user/$UID' >> ~/.bashrc
source ~/.bashrc
```

The `XDG_RUNTIME_DIR` line preempts the same systemd issue we hit with Hermes (see Phase 5 / gateway guide).

### 6.2 Install Kilo CLI

```
npm i -g @kilocode/cli
kilo --version
```

You should see version 7.2 or newer (April 2026).

### 6.3 Enable lingering for the kilo user

So any kilo systemd services or background processes survive SSH disconnects. From your **root** window:

```
loginctl enable-linger kilo
loginctl show-user kilo | grep Linger     # expect: Linger=yes
```

## Phase 7 — Configure OpenRouter for Kilo

In your kilo session:

```
mkdir -p ~/.config/kilo
cat > ~/.config/kilo/env <<'EOF'
KILO_PROVIDER=openrouter
OPENROUTER_API_KEY=sk-or-v1-REPLACE_ME
OPENROUTER_MODEL=anthropic/claude-sonnet-4-6
EOF
chmod 600 ~/.config/kilo/env
echo 'set -a; source ~/.config/kilo/env; set +a' >> ~/.bashrc
source ~/.bashrc
```

The `set -a; source ...; set +a` pattern exports each line of the env file into the shell environment automatically on every login.

Verify by running an interactive Kilo session:

```
kilo
```

When it finishes its first-run setup, type a one-line task ("write a hello-world fastapi app and explain it") to confirm the model is reachable.

## Phase 8 — Verification: confirm both agents are healthy and isolated

From root:

```
# Both home directories are private
ls -ld /home/hermes /home/kilo

# Cross-user reads are denied
sudo -u kilo ls /home/hermes 2>&1     # Permission denied
sudo -u hermes ls /home/kilo 2>&1     # Permission denied

# Secrets files are mode 600
sudo -u hermes stat -c '%a %n' /home/hermes/.hermes/.env
sudo -u kilo   stat -c '%a %n' /home/kilo/.config/kilo/env

# No public ports beyond SSH
ufw status numbered
ss -tlnp | grep -v 127.0.0.1            # only sshd should listen on 0.0.0.0:22

# Hermes is running
sudo -u hermes XDG_RUNTIME_DIR=/run/user/$(id -u hermes) systemctl --user status hermes-gateway | head

# Kilo CLI works
sudo -u kilo bash -lc 'kilo --version'
```

Once all of those are clean, you have two independent autonomous coding agents on a single hardened VPS, each restricted to its own user, both pointed at OpenRouter, with no public web exposure beyond SSH.

## Operational habits

### Run agents inside `tmux`

Long agent runs survive SSH disconnects this way:

```
sudo -iu hermes
tmux new -s hermes
hermes
```

Detach without killing the run with `Ctrl+B` then `D`. Reattach with `tmux attach -t hermes`.

### Two windows, always

Open two PowerShell windows from the start: one for the agent user, one for root. You'll need to flip back and forth — installs, service control, log tailing.

### Watch live logs

```
journalctl --user -u hermes-gateway -f       # as the hermes user
```

Hermes' default log level only emits warnings and errors. To see message receipt and processing, edit `~/.hermes/config.yaml` and bump log level to `INFO` or `DEBUG`, then restart the gateway.

### Rotate keys quarterly

OpenRouter and Discord bot tokens both have rotation flows. Set yourself a quarterly calendar reminder. Both updates are a single edit in `/home/hermes/.hermes/.env` followed by `systemctl --user restart hermes-gateway`.

### Dispose-and-rebuild is cheap

If anything goes sideways: `deluser --remove-home hermes && deluser --remove-home kilo`, recreate the users, re-run Phases 4–7. Total time: ~20 minutes. The system phases (1–3) survive untouched. This is a feature of the architecture, not a bug.

## Where to read more

- [Discord Gateway: Setup, Troubleshooting & Channel Architecture](https://openclawdatabase.com/hermes/discord-gateway/) — the deep dive on Discord setup, the `auto_thread` trap, channel-permission overrides, systemd lingering, the bus-not-found error.
- [Hermes + Kilo Code Troubleshooting & FAQ](https://openclawdatabase.com/hermes/troubleshooting/) — every error message we hit while writing this, with the fix.

If something here is wrong or out of date, the fastest sanity check is `hermes --version` on the box itself — Hermes ships a built-in update checker. Same for `kilo --version`.

## More Hermes Guides

Continue your Hermes journey — every guide on the hub:

 [⚡ Quick Start — 20 Minutes Install Hermes, run the setup wizard, start the daemon, pick a model, submit your first scheduled task.](https://openclawdatabase.com/hermes/setup/)

 [💬 Discord Gateway — The Definitive Setup Five silent failure modes solved. Developer Portal, the systemd linger + bus-socket fix, the auto_thread trap, channel architecture.](https://openclawdatabase.com/hermes/discord-gateway/)

 [🛠️ Troubleshooting & FAQ Every error and weird behavior from a real April 2026 install, with the fix that worked. SSH, install, runtime, Discord, systemd, Kilo, FAQ.](https://openclawdatabase.com/hermes/troubleshooting/)

 [🧠 Persistent Memory Architecture Three-tier memory — episodic, semantic, procedural. SQLite vs PostgreSQL, compression, retrieval tuning.](https://openclawdatabase.com/hermes/memory/)

 [🗓 Long-Running Tasks & Scheduling TASKS.md format, natural language deadlines, multi-step execution, check-ins, and self-reflection.](https://openclawdatabase.com/hermes/tasks/)

 [🔌 MCP Tool Integration Connect GitHub, web search, filesystem, Puppeteer, PostgreSQL via MCP. v0.9 adapter and v1.0 native MCP.](https://openclawdatabase.com/hermes/mcp-tools/)

 [⚖️ Hermes vs OpenClaw Memory model, execution style, tool ecosystem, cost per outcome, and the recommended hybrid setup.](https://openclawdatabase.com/hermes/vs-openclaw/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)

← Back to [Hermes hub](https://openclawdatabase.com/hermes/) · Next: [Discord Gateway →](https://openclawdatabase.com/hermes/discord-gateway/)



================================================================
# Hermes vs OpenClaw 2026 — Which Agent Platform Is Right.
URL: https://openclawdatabase.com/hermes/vs-openclaw/
Last updated: 2026-05-30
================================================================

# Hermes vs OpenClaw — Which Platform Is Right for You?

Hermes and OpenClaw solve different problems. OpenClaw is a conversational agent: you talk to it, it does things, the conversation ends. Hermes is an autonomous agent: you give it a goal with a deadline, it plans and executes across hours or days, and checks in when it needs you. The question isn't which is better — it's which fits the task. Most serious users end up running both.

## The Core Difference

The architectural difference that drives everything else: **OpenClaw is session-scoped, Hermes is goal-scoped.**

- **OpenClaw** — you open a conversation, give instructions, get responses. The context lives for the duration of the session. When you close it, it's done. Memory carries over via MEMORY.md files, but execution doesn't.
- **Hermes** — you submit a goal. Hermes plans it, executes it across multiple scheduled steps, and completes it — with or without you present. Memory is a database that grows across months, not a file you manually maintain.

## Full Comparison

| Dimension | OpenClaw | Hermes |
| --- | --- | --- |
| **Execution model** | Conversational — you drive each turn | Autonomous — runs to completion without prompting |
| **Memory model** | Session context + MEMORY.md file (manual) | SQLite/PostgreSQL database with 3 memory types; auto-grows |
| **Memory duration** | As long as you maintain MEMORY.md | Indefinite — database persists until you delete it |
| **Task duration** | One session (minutes to hours) | Hours to weeks; survives restarts |
| **Scheduling** | Via HEARTBEAT.md cron (simple) | First-class feature — natural language scheduling, recurring tasks, deadlines |
| **Tool ecosystem** | 53 official skills + 13,700+ community | MCP tools (100+ servers, growing open standard) |
| **Tool compatibility** | OpenClaw skills only | Any MCP-compatible server |
| **Self-improvement** | No — same behavior across sessions | Yes — reflection cycle writes procedural memory that influences future tasks |
| **Setup time** | Under 10 minutes | ~20 minutes |
| **Channels** | WhatsApp, Telegram, Discord, email, iMessage | Telegram and Discord (full gateway); email for alerts |
| **Conversational quality** | Excellent — designed for back-and-forth | Good but not optimised — Hermes is an executor, not a conversational partner |
| **Skill/tool writing** | SKILL.md format — agent writes them | MCP server format — requires Node.js or Python code |
| **Cost model** | Pay per conversation turn | Pay per task step (potentially far fewer calls for equivalent work) |
| **Typical monthly cost** | $3–20 depending on usage | $5–30 depending on task complexity and frequency |
| **Best model choice** | Haiku for most tasks, Sonnet for complex | Sonnet default, Opus for heavy reasoning, auto-escalation |
| **License** | MIT (fully free) | MIT (fully free) |
| **Maturity** | Stable, large community | v0.15.2 — stable, MCP native support included, no longer experimental |

## When to Choose OpenClaw

- You want to **talk to your agent** — back and forth, real time
- Tasks complete in a single session (under a few hours)
- You want WhatsApp or iMessage as a channel (Hermes supports Telegram and Discord but not WhatsApp/iMessage)
- You want the richest skill ecosystem — 53 official + community options
- You're new to self-hosted agents — OpenClaw is simpler to start with
- You need group chat support for a team setting

## When to Choose Hermes

- Tasks that take **more than a few hours** and don't need you at every step
- Research projects spanning days or weeks
- You want the agent to **improve itself** — better approaches on similar tasks over time
- You need a proper **memory database**, not a markdown file you maintain manually
- You want to schedule goals, not just cron jobs — "finish this by Friday" rather than "run this command at 9am"
- You're using MCP tools that work across clients (Claude Desktop, Cursor, Hermes all share the same servers)

## Running Both Together (Recommended Setup)

The most powerful setup is to run both simultaneously and route tasks to whichever is better suited:

| Task type | Use |
| --- | --- |
| Quick questions, conversational help, real-time drafting | OpenClaw |
| Morning brief, email triage, GitHub notifications check | OpenClaw (via HEARTBEAT.md) |
| Research projects spanning multiple days | Hermes |
| Complex analysis that requires reading many sources | Hermes |
| Recurring monitoring with adaptive responses | Hermes |
| Writing long documents that need consistent context | Hermes |
| WhatsApp or iMessage interaction | OpenClaw (Hermes doesn't support WhatsApp/iMessage) |

They run on different ports and don't interfere:

```
# OpenClaw on 18789 — for conversational use
openclaw gateway   # background via systemd

# Hermes on 18791 — for long-running tasks
hermes start       # daemon mode via systemd

# Both share a Telegram bot — route by prefix:
# "hermes: research AI memory for the next week" → goes to Hermes
# "what's the weather today?" → goes to OpenClaw
```

Configure routing in your Telegram bot's SOUL.md or PERSONA.md: tell OpenClaw that messages starting with "hermes:" should be passed to the Hermes API endpoint, and everything else handled normally.

## Sharing Memory Between Hermes and OpenClaw

The two systems use different memory formats — Hermes has a database, OpenClaw has MEMORY.md. But you can bridge them:

- **Hermes → OpenClaw:** Add a Hermes recurring task that exports a summary of key facts from Hermes's semantic memory to OpenClaw's MEMORY.md weekly. Hermes can write files to any path you grant.
- **OpenClaw → Hermes:** Use the Hermes CLI to manually add facts from OpenClaw sessions: `hermes memory fact add "..."`
- **Shared workspace files:** Point both systems at the same workspace directory (set `~/.hermes/workspace` to the same path as `~/.openclaw/workspace`) — SOUL.md/PERSONA.md, MEMORY.md, and notes files are readable by both.

## Cost Comparison in Practice

A common concern: "Hermes runs longer tasks — does it cost more?" Not necessarily. The comparison that matters is *cost per outcome*, not cost per API call:

| Task | OpenClaw approach | Hermes approach | Cost comparison |
| --- | --- | --- | --- |
| Research 20 sources and write a report | You guide it through 40+ conversation turns across several sessions | Submit once, Hermes executes 8–12 steps autonomously | Hermes: 2–3× cheaper (fewer context tokens re-sent) |
| Morning brief | Heartbeat cron, runs in <60 seconds | Scheduled task, similar execution | Roughly equal |
| Quick question | One turn, done | Overhead of task planning + execution | OpenClaw: 5–10× cheaper for simple Q&A |
| Monitor and react to changes over a week | Multiple manual sessions as things change | One task with check-ins; Hermes adapts autonomously | Hermes: significantly cheaper and more thorough |

## More Hermes Guides

Continue your Hermes journey — every guide on the hub:

 [⚡ Quick Start — 20 Minutes Install Hermes, run the setup wizard, start the daemon, pick a model, submit your first scheduled task.](https://openclawdatabase.com/hermes/setup/)

 [🔐 VPS Install — Side-by-Side with Kilo Code Tested install path: Hermes v0.11+ and Kilo CLI on one Hetzner Ubuntu 24.04 VPS. Per-user isolation, OpenRouter, no public ports.](https://openclawdatabase.com/hermes/vps-install/)

 [💬 Discord Gateway — The Definitive Setup Five silent failure modes solved. Developer Portal, the systemd linger + bus-socket fix, the auto_thread trap, channel architecture.](https://openclawdatabase.com/hermes/discord-gateway/)

 [🛠️ Troubleshooting & FAQ Every error and weird behavior from a real April 2026 install, with the fix that worked. SSH, install, runtime, Discord, systemd, Kilo, FAQ.](https://openclawdatabase.com/hermes/troubleshooting/)

 [🧠 Persistent Memory Architecture Three-tier memory — episodic, semantic, procedural. SQLite vs PostgreSQL, compression, retrieval tuning.](https://openclawdatabase.com/hermes/memory/)

 [🗓 Long-Running Tasks & Scheduling TASKS.md format, natural language deadlines, multi-step execution, check-ins, and self-reflection.](https://openclawdatabase.com/hermes/tasks/)

 [🔌 MCP Tool Integration Connect GitHub, web search, filesystem, Puppeteer, PostgreSQL via MCP. v0.9 adapter and v1.0 native MCP.](https://openclawdatabase.com/hermes/mcp-tools/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)

← Back to [Hermes hub](https://openclawdatabase.com/hermes/) · See also: [Hermes Quick Start](https://openclawdatabase.com/hermes/setup/) · [OpenClaw Quick Start](https://openclawdatabase.com/openclaw/setup/) · [IronClaw vs OpenClaw](https://openclawdatabase.com/ironclaw/vs-openclaw/)