🏛️ Hermes Agent

1. What Is Hermes Agent?

Hermes Agent is an open-source AI assistant framework by Nous Research. It provides:

• A full Python AI agent core (~10,700 lines) with 18+ LLM provider integrations
• A multi-platform messaging gateway (18 platforms: Telegram, Discord, WhatsApp, Signal, Slack, Matrix, etc.)
• A skills system compatible with agentskills.io
• An MCP client for external tool servers
• An IDE plugin adapter (ACP) for VS Code, Zed, and JetBrains
• CLI workflows, cron scheduling, and RL training environments (Atropos)
• SQLite-based session persistence with full-text search

MIT License · Python 3.11+ · github.com/nousresearch/hermes-agent

2. Prerequisites

System Requirements

Required Accounts & Tokens

Before installing, gather at least one LLM API key:

You also need platform-specific tokens for each messaging channel you enable (Telegram bot token, Discord bot token, etc.).

System Dependencies

# Install Python 3.11+ and git if not present
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3-pip git

# Verify Python version
python3 --version

3. Installation

Method A — Installer Script (Recommended)

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

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

hermes --version

Method B — Source Install

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

# Install uv package manager first
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env   # or source ~/.bashrc

# Install Hermes with all extras (includes MCP support)
pip install -e ".[mcp]"
# OR for full extras:
pip install -e ".[full]"

Post-Install Setup

# 1. Interactive first-run wizard
hermes setup

# 2. Select your LLM provider + enter API key
hermes model

# 3. Configure messaging platforms
hermes gateway setup

# 4. Add to shell profile
echo 'source ~/.hermes/hermes.sh' >> ~/.bashrc   # if installer created one
# OR simply ensure ~/.local/bin is in PATH (done in Step 2 above)

4. Configuration

Config Directory Structure

Hermes stores everything in ~/.hermes/:

~/.hermes/
├── config.yaml       # Main configuration file
├── .env              # API keys and secrets
├── auth.json         # Messaging platform credentials
├── SOUL.md           # Agent personality (optional)
├── memories/         # Long-term memory files
├── skills/           # Installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Session data (SQLite)
└── logs/             # Log files

Key Environment Variables

Messaging Platform Setup

# Start the interactive gateway setup wizard
hermes gateway setup

# WhatsApp pairing flow (QR code)
hermes whatsapp

# Approve DM pairing requests
hermes pairing approve <platform> <code>

# Example: Approve a Telegram user
hermes pairing approve telegram 12345

Skills Configuration

# Skills live in ~/.hermes/skills/ (SKILL.md format)
# Optional external skill directories (read-only) can be added in config.yaml

# Agent can create/update/delete skills via the skill_manage tool
# Bundled skills are in the agentskills.io catalog

5. Running & Operations

Start / Stop / Restart

Auto-Start on Boot (systemd)

# User-level service (recommended for VPS)
hermes gateway install

# System-level service (requires sudo)
sudo hermes gateway install --system

# Check status
hermes gateway status --system

tmux new -s hermes
hermes gateway run
# Press Ctrl+B, D to detach

Logs

# View/tail logs
hermes logs

# Filter by type
hermes logs --type agent
hermes logs --type gateway
hermes logs --type error

# Diagnostic check
hermes doctor

Log files are stored in ~/.hermes/logs/.

Updates

# Pull latest code + reinstall dependencies
hermes update

# Check version
hermes --version

Backup & Restore

# Built-in backup (creates a zip of ~/.hermes/)
hermes backup

# Restore from backup
hermes import /path/to/backup.zip

# Manual backup
zip -r ~/.hermes/ heremes-backup-$(date +%Y%m%d).zip

6. Messaging Platform Quick Reference

7. MCP Integration

Hermes includes an MCP (Model Context Protocol) client for connecting to external tool servers:

# MCP is configured in config.yaml under the mcpServers section
# Supports both stdio and HTTP (with header auth)

# Example: Adding an MCP server
# In ~/.hermes/config.yaml:
#
# mcpServers:
#   my-server:
#     type: stdio
#     command: ["npx", "-y", "@some/mcp-server"]
#   remote-server:
#     type: http
#     url: "https://my-server.example.com/mcp"
#     headers:
#       Authorization: "Bearer ${MY_API_KEY}"

8. Coexistence with OpenClaw

No port conflicts. OpenClaw binds to 127.0.0.1:18789; Hermes uses internal port allocation by default. If you enable Hermes' optional API server, pick a different port.

WhatsApp — Both on Same Account?

Resource Usage on Your VPS

Recommended Setup for Dual Install

# 1. Run OpenClaw (already configured)
openclaw daemon status   # or systemctl --user status openclaw

# 2. Install Hermes (don't reinstall OpenClaw)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 3. Point Hermes to a different config dir (optional)
export HERMES_HOME=/opt/hermes/config   # if you want it fully separate

# 4. Use different bot tokens for each platform
# OpenClaw: Bot A for Telegram, Bot B for Discord
# Hermes:   Bot C for Telegram, Bot D for Discord

# 5. Set ALLOWED_USERS on Hermes to restrict access
echo "TELEGRAM_ALLOWED_USERS=YOUR_USER_ID" >> ~/.hermes/.env
echo "DISCORD_ALLOWED_USERS=YOUR_DISCORD_ID" >> ~/.hermes/.env

9. Sources & Docs

• Hermes Agent GitHub
• Official Documentation
• Installation Guide
• Messaging Setup
• Environment Variables Reference
• CLI Commands Reference