Hermes Agent Setup

What You'll Need

• A Hermes Agent install (see install guide)
• One model provider API key (Anthropic, OpenRouter, or Google AI Studio)
• One chat-platform token (Telegram bot, Discord app, or WhatsApp number)
• A domain or subdomain pointing at your server (for production)

Step 1: Initialize the Config

Hermes creates a default config on first run, but you'll want to edit it directly:

# Default config location
cat ~/.hermes/config.json

# Or initialize a fresh one
hermes init

Step 2: Pick a Model

Hermes is model-agnostic. The two safe starting picks for new setups:

Anthropic (best quality)

{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-..."
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" }
    }
  }
}

OpenRouter (most flexible)

{
  "models": {
    "providers": {
      "openrouter": {
        "apiKey": "sk-or-..."
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "openrouter/anthropic/claude-sonnet-4.6" }
    }
  }
}

See the Hermes + OpenRouter guide for free-tier model picks.

Step 3: Configure Memory

Hermes's headline feature is multi-level persistent memory. Defaults are reasonable, but verify the storage path:

{
  "memory": {
    "store": {
      "path": "~/.hermes/memory",
      "compactionInterval": "24h"
    },
    "levels": {
      "session": true,
      "file": true,
      "longTerm": true
    }
  }
}

See the Hermes memory guide for what each level stores and how compaction works.

Step 4: Connect a Chat Platform

Pick one to start. You can add more later. Most users start with Telegram:

Telegram

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC...",
      "dmPolicy": "pairing"
    }
  }
}

Get a bot token from @BotFather on Telegram. Use dmPolicy: "pairing" so random users can't spam your bot. See the Hermes + Telegram guide for the full walkthrough.

Discord

{
  "channels": {
    "discord": {
      "enabled": true,
      "botToken": "...",
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  }
}

Get a bot token at discord.com/developers. See the Hermes + Discord guide.

Step 5: Set Gateway Auth

Even in production, you'll occasionally hit the web UI. Set a long random token:

# Generate a random token
openssl rand -hex 32

# Add to config
{
  "gateway": {
    "auth": { "token": "PASTE_THE_TOKEN_HERE" },
    "port": 8787
  }
}

Step 6: Expose the Gateway (Production)

If your bot needs to receive webhooks (Discord, WhatsApp, Telegram), the gateway must be reachable from the internet. Put Caddy in front:

# /etc/caddy/Caddyfile
hermes.example.com {
  reverse_proxy localhost:8787
}

Caddy handles TLS automatically. For self-hosted setups, see the Hermes on a VPS guide for the full hardening checklist.

Step 7: Start and Verify

# Start Hermes
hermes start

# Tail logs to verify model + channel are connected
hermes logs --follow

# In another terminal, check status
hermes status

Send a test message to your Telegram bot. The first response can take ~10–30 seconds while Hermes warms up the model and memory store. Subsequent messages are instant.

Common First-Time Mistakes

• Wrong model ID format. Use openrouter/anthropic/claude-sonnet-4.6 — the leading provider name is required.
• Channel enabled but not registered. Both channels.X.enabled AND plugins.entries.X.enabled must be set.
• Gateway bound to 0.0.0.0 without auth. Anyone can use your bot — and your API key.
• Open dmPolicy on Telegram. Random users will spam it. Use pairing instead.

Skip the Setup — Managed Hermes