Hermes Agent

Hermes Agent is an open-source, self-improving AI agent by Nous Research. It connects to messaging platforms (Telegram, Discord, Slack), uses tools, remembers conversations, and autonomously creates new skills over time.

Configuration

services:
  ai-agent:
    package: hermes
    config:
      llm_api_key: "${OPENROUTER_API_KEY}"
      llm_model: "anthropic/claude-sonnet-4"
      telegram_bot_token: "${TELEGRAM_BOT_TOKEN}"
      telegram_allowed_users: "12345678"

Parameters

Parameter	Required	Default	Description
llm_provider	No	openrouter	LLM provider: openrouter, openai, anthropic (or claude)
llm_api_key	Yes		API key for the LLM provider
llm_model	Yes		Model to use (provider-specific)
telegram_bot_token	No		Telegram bot token
telegram_allowed_users	No		Comma-separated Telegram user IDs allowed to interact
discord_bot_token	No		Discord bot token
slack_bot_token	No		Slack bot token
slack_app_token	No		Slack app-level token for Socket Mode
webhook_enabled	No	false	Enable Telegram webhook mode (requires public IP)
webhook_port	No	8443	Port for Telegram webhook listener
env	No		Extra environment variables to pass to Hermes (see below)

LLM providers

Hermes works with any OpenAI-compatible API. Set llm_provider and llm_api_key accordingly:

# OpenRouter (default), access to 200+ models
config:
  llm_provider: openrouter
  llm_api_key: "${OPENROUTER_API_KEY}"
  llm_model: nousresearch/hermes-3-llama-3.1-405b

# OpenAI
config:
  llm_provider: openai
  llm_api_key: "${OPENAI_API_KEY}"
  llm_model: gpt-4o

# Anthropic (also accepts 'claude')
config:
  llm_provider: anthropic
  llm_api_key: "${ANTHROPIC_API_KEY}"
  llm_model: claude-sonnet-4-6

Messaging integrations

At least one messaging integration is recommended so you can interact with your agent remotely.

Telegram

1. Message @BotFather on Telegram and create a new bot
2. Copy the bot token
3. Get your Telegram user ID by messaging @userinfobot
4. Set telegram_bot_token and telegram_allowed_users

By default, Telegram runs in polling mode (no public port needed). Set webhook_enabled: true if you want webhook mode instead, this requires port 8443 to be reachable from the internet.

Discord

1. Create a bot in the Discord Developer Portal
2. Copy the bot token and set discord_bot_token

Slack

1. Create a Slack app with Socket Mode enabled
2. Set both slack_bot_token and slack_app_token

Extra environment variables

Use env to pass additional settings directly to Hermes without needing a dedicated parameter for each one:

config:
  llm_provider: anthropic
  llm_api_key: "${ANTHROPIC_API_KEY}"
  llm_model: claude-sonnet-4-6
  telegram_bot_token: "${TELEGRAM_BOT_TOKEN}"
  telegram_allowed_users: "12345678"
  env:
    HERMES_AGENT_TIMEOUT: "0"
    GATEWAY_ALLOW_ALL_USERS: "true"

Any key-value pair under env is written as an environment variable in the Hermes .env file. See the Hermes Agent docs for available variables.

Backups

Hermes data (skills, memory, conversation history, user profiles) is backed up to object storage every 24 hours. The last 7 backups are retained.

Manual backup

managed service ai-agent backup

Restore from backup

managed service ai-agent restore --arg confirm=yes

This restores from the most recent backup. To restore a specific backup:

managed service ai-agent restore --arg confirm=yes --arg backup=backups/ai-agent-1/20260402-120000.tar.gz

Commands

Command	Description
managed service <name> status	Show agent status, data size, and skill count
managed service <name> backup	Create a backup now
managed service <name> restore	Restore from backup
managed service <name> logs	Show recent logs

How it works

The service installs Hermes Agent from source on a single server, running as a systemd service (hermes.service) under a dedicated hermes user. All agent data lives in /opt/hermes/data/.

The agent runs in gateway mode, which handles all configured messaging integrations in a single process. It connects to your chosen LLM provider for inference, no local GPU is required.