Hermes Agent: Complete Setup Guide

Hermes Agent is a personal AI assistant that runs as a Telegram bot with full access to your development environment via MCP (Model Context Protocol). It provides natural language access to your codebase, terminal, files, and tools — all through Telegram, with optional bidirectional voice messaging.

This guide covers everything: installation, configuration, endpoint setup, MCP servers modelcontextprotocol/servers, voice support, and troubleshooting.

What Is Hermes Agent?

Hermes Agent is a lightweight AI assistant that integrates with your local system through Telegram. It runs on the github.com/NousResearch/hermes-agent">Hermes Agent framework (built by Kilo.AI) with custom MCP tooling, voice support, and deep project integration.

Key capabilities:

• Telegram-first interface — Chat from anywhere, mobile or desktop
• Full filesystem access — Read, write, search across your projects
• Terminal execution — Run commands, scripts, git operations
• MCP protocol — Extend with any MCP server (GitHub, browser, databases)
• Bidirectional voice — Send voice, get voice back (voice cloning supported)
• Project context — Automatic codebase indexing and semantic search

Architecture Overview

Prerequisites

• Ubuntu 22.04+ (or any Linux with systemd) — also works on macOS, WSL2, and Termux
• Python 3.11+ — the installer creates a venv automatically
• Node.js nodejs.org 18+ — required for MCP servers (filesystem, git, shell, browser). Install with:

  curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
  sudo apt install -y nodejs
  node --version  # verify ≥ 18

• Telegram Bot Token — from @BotFather
• API Keys — at least one model provider (OpenRouter, Anthropic, OpenAI, or Kilo.ai)
• Git — for cloning and version control

Part 1: Install Hermes Agent

Installation

The official one-line installer handles all dependencies (Python venv, Node.js, ffmpeg, ripgrep) automatically:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc  # or ~/.zshrc
hermes --version   # verify installation

Initial Setup Wizard

Hermes Agent provides an interactive setup wizard that configures everything for you — no manual YAML editing needed. Run:

hermes setup        # Full guided setup (bot token, API keys, MCP servers)
hermes model        # Configure model provider only
hermes tools        # Select which MCP tools to enable

The wizard walks you through provider selection, API key entry, and connectivity testing. Manual file editing is only needed for advanced customization.

Option: Manual Installation

If you prefer manual control or need to install from source:

git clone https://github.com/Kilo-AI/hermes-agent.git ~/.hermes
cd ~/.hermes
pip install -e .

Option B: Docker (for isolation)

docker run -d \
  --name hermes-agent \
  -v ~/.hermes:/app/.hermes \

      

        ℹ️ Prepare config directory: Create ~/.hermes first so the container can mount it:
        
mkdir -p ~/.hermes
      
      

        ℹ️ docker-compose recommended: For easier volume and dependency management, use a docker-compose.yml instead of raw docker run.
      
  -v /path/to/your/projects:/projects \
  -e HERMES_TELEGRAM_TOKEN="***" \
  -e KILOCODE_API_KEY="***" \
  kiloai/hermes-agent:latest

Part 2: Configure Telegram Bot

Create Bot with BotFather

1. Open Telegram, search for @BotFather
2. Send /newbot
3. Name it (e.g., Hermes Assistant)
4. Choose a username (e.g., hermes_assistant_bot)
5. BotFather returns a token — save it as HERMES_TELEGRAM_TOKEN

Set Bot Commands (optional but recommended)

Send this to @BotFather with /setcommands:

/start — Start the agent
/help — Show available commands
/run — Execute a shell command
/read — Read a file
/search — Search across files
/chat — Direct chat mode
/model — Switch AI model
/voice — Toggle voice mode

Part 3: Configure Model Provider

Hermes Agent supports multiple providers via the Kilo Gateway. The default is kilocode/kilo-auto/free (Kilo.AI's free tier).

Provider Options

Set API Keys

Create the ~/.hermes/.env file with your actual keys:

cat > ~/.hermes/.env << 'EOF'
KILOCODE_API_KEY="your-kilo-api-key"
OPENROUTER_API_KEY="your-openrouter-key"
ANTHROPIC_API_KEY="your-anthropic-key"
OPENAI_API_KEY="your-openai-key"
TELEGRAM_BOT_TOKEN="your-telegram-bot-token"
ELEVENLABS_API_KEY="your-elevenlabs-key"
EOF
chmod 600 ~/.hermes/.env

Configure Default Model

# ~/.hermes/config.yaml
model:
  default: kilocode/kilo-auto/free
  provider: kilocode
  fallback_chain:
    - openrouter/anthropic/claude-3.5-sonnet
    - ollama/llama3.2

Part 4: MCP Servers — The Tool Layer

MCP (Model Context Protocol) servers give Hermes access to external tools. They run as separate processes and connect via stdio.

Essential MCP Servers

MCP Configuration

# ~/.hermes/mcp_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
    },
    "shell": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-shell"]
    },
    "github": {
      "command": "python",
      "args": ["-m", "mcp_github", "--token", "ghp_xxxxxxxxxxxx"]
    }
  }
}

ollama pull llama3.2
# In config, set context to ≥ 65536

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

"filesystem": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/USER/projects", "/home/USER/work"]
}

Part 5: Voice Support (Optional)

Hermes Agent supports bidirectional voice messaging via TTS (text-to-speech) and STT (speech-to-text).

Configure TTS

# ~/.hermes/config.yaml — add:
voice:
  tts_engine: "elevenlabs"  # or "openai", "coqui", "xtts"
  stt_engine: "openai-whisper"
  voice_id: "21m00Tcm4TlvDq8ikWAM"  # ElevenLabs elevenlabs.io voice ID
  sample_rate: 24000

Install Voice Dependencies

# For ElevenLabs
pip install elevenlabs

# For local XTTS v2
pip install TTS torch

# For OpenAI Whisper (STT)
pip install openai-whisper

Once configured, send a voice message in Telegram and Hermes will transcribe it, process it, and reply with a voice message.

Gateway Setup — Required for Telegram

The Hermes Agent uses a two-process architecture:

• Agent process — LLM inference, tool execution, reasoning
• Gateway process — messaging channels (Telegram, Discord, webhooks)

Without the gateway running, the bot will not receive or send messages. Set it up:

hermes gateway setup   # Interactive: maps Telegram chats to agents
hermes gateway start    # Start the gateway

Running Gateway as a Service

For production, run the gateway as a user systemd service so it survives logout and auto-restarts on failure.

First, enable lingering for your user (allows user services without an active login session):

sudo loginctl enable-linger $USER

Create the gateway service file at ~/.config/systemd/user/hermes-gateway.service:

[Unit]
Description=Hermes Messaging Gateway
After=network.target

[Service]
Type=simple
User=%i
ExecStart=/usr/local/bin/hermes gateway start
Restart=always
RestartSec=10
EnvironmentFile=/home/%i/.hermes/.env

[Install]
WantedBy=default.target

Then enable and start it:

systemctl --user daemon-reload
systemctl --user enable --now hermes-gateway
systemctl --user status hermes-gateway

Part 6: Starting the Agent

Start as a Service (recommended)

# Copy systemd service file
sudo cp ~/.hermes/hermes-agent.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable and start
sudo systemctl enable hermes-agent
sudo systemctl start hermes-agent

# Check status
sudo systemctl status hermes-agent

Or Run Manually

# From terminal (foreground)
hermes start --verbose

# Or as background process
hermes start --daemon

Part 7: Verify Installation

Before testing via Telegram, verify locally:

hermes --version                  # Check installation
hermes start --verbose             # Run in foreground (watch logs)
hermes mcp status                  # Check MCP servers
hermes doctor                      # Full system diagnostics
hermes config show                 # View current configuration

If all checks pass, send a message to your Telegram bot. It should respond within seconds.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"