Hermes Agent Workstation

This project provides a robust, containerized deployment setup for the NousResearch/Hermes-Agent designed to run smoothly on a local workstation via Docker. It integrates Python tools for testing, linting, and formatting using uv as the package manager, alongside GitHub actions and pre-commit hooks to ensure high software engineering standards.

Architecture

The diagram below illustrates the deployment architecture:

graph TD
    A[User / Messaging Client<br>e.g., Telegram] -->|Sends Message| B(Telegram Servers)
    B <-->|Long-polling / Webhooks| C[Hermes Gateway<br>Docker Container]

    subgraph Workstation
        D[~/.hermes_agent/] <-->|Volume Mount: /opt/data| C
        C -->|Depends On| E[Hermes Dashboard<br>Docker Container]
        E -->|API & UI Access| F[Localhost:9119]
    end

    C <-->|Makes Live API Calls| G[LLMs / Tools API<br>e.g., OpenAI, Search APIs]

Loading

Components

• Hermes Gateway: The core background service processing events, cron tasks, and bridging messaging platforms (e.g., Telegram) to the Hermes agent logic.
• Hermes Dashboard: A web UI for managing sessions, tools, and configuring agent states, running on port 9119.
• Persistent Data Volume: Mapped from ~/.hermes_agent/ on the host to /opt/data inside the container. This ensures that agent history, credentials, pairing sessions, and configurations survive container restarts and updates.

Prerequisites

• Docker and Docker Compose
• uv (for running local scripts, tests, and linters)
• Python 3.12+
• A Telegram Bot Token if using Telegram integration

Quick Start: Getting Your Agent Online

Follow these exact steps to boot your Hermes agent and start chatting with it on Telegram.

1. Create a Telegram Bot (via BotFather)

Before starting Hermes, you need a Telegram Bot Token:

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts to name your bot and give it a username (must end in bot).
3. BotFather will reply with an HTTP API Token (e.g., 1234567890:ABCdefGhIJKlmNoPQRsTuvwxyZ). Copy this token.

2. Configure Environment Variables

Create a file named .env in the root of this project repository. Add your Telegram token and your AI Provider key (e.g., Google Gemini):

# .env
TELEGRAM_BOT_TOKEN="your_telegram_bot_token_here"
GOOGLE_API_KEY="your_google_api_key_here"

(Note: .env is ignored by git, so your keys remain safe.)

3. Initialize the Host Volume

Hermes needs a place to store its long-term memory and databases so they aren't wiped when Docker restarts. Initialize the host directory by running:

make setup

(This creates ~/.hermes_agent/ on your workstation and syncs Python dependencies).

4. Boot the Container

Start the Hermes gateway and dashboard in the background using Docker Compose:

make run

You can verify it started successfully by checking the logs:

make logs

5. Pair with Your Agent securely

Hermes is highly secure out-of-the-box. It won't talk to random strangers on Telegram until you "pair" with it:

1. Open Telegram and send a message to your new bot.
2. The bot will refuse to answer but will reply with a unique pairing code (e.g., XKGH5N7P).
3. Open your terminal and run the following command to approve your Telegram account, replacing the code with yours:

   make pair CODE=XKGH5N7P

4. You are now securely authenticated! The bot will now obey your commands and remember you.

Configuration (config.yaml & SOUL.md)

Hermes reads its configuration dynamically using file mounts from the Git repository. While databases and persistent session state are stored in ~/.hermes_agent/ on the workstation, the behavior and identity configs are managed right here in the repository under the hermes-config/ directory.

1. config.yaml (Models, Behaviors, Tools)

The file hermes-config/config.yaml controls how Hermes acts. You can set up your models, backend instructions, and subagent thresholds here. Example config.yaml setup:

model:
  provider: "google"
  model: "gemini-2.5-flash"

2. SOUL.md (Bot Soul / Identity)

To customize the core identity and system prompt of your bot, edit the hermes-config/SOUL.md file. The text inside this file will override the default DEFAULT_AGENT_IDENTITY natively.

3. Environment Variables & .env

Secret values must never be pushed to version control. The setup automatically loads environment variables from a .env file located in the root directory (where the Makefile lives).

A template is provided! Simply copy the .env.example to .env:

cp .env.example .env

Then, open the new .env file and fill in your keys (e.g., TELEGRAM_BOT_TOKEN, GOOGLE_API_KEY). (Note: .env is specifically ignored by git, ensuring your keys remain completely safe).

Configuration Versioning via Git

You can instruct Hermes to automatically version and backup its configuration files using a Personal Access Token (PAT). To do this, add the following to your .env file:

GIT_REPO_URL="https://github.com/your-username/hermes-agent-config.git"
GIT_PAT="your_github_personal_access_token_here"

The agent reads these variables and will push configuration updates to this remote repository seamlessly.

TELEGRAM_BOT_TOKEN="your_telegram_bot_token"
GOOGLE_API_KEY="your_google_api_key_for_gemini"

Development and Testing

We follow strict formatting and linting rules enforced via pre-commit hooks and GitHub actions.

• Format Code:

  make format

• Lint Code:

  make lint

• Run Tests: We test real integration with the live APIs where applicable.

  make test