This guide walks you through installing Hermes in a Docker container, keeping it fully isolated from your host system while preserving a clean main environment. The installation is configured to use OpenRouter with a free AI model by default, making it easy to get started at no cost. You can switch to a different supported model at any time directly from the Hermes prompt. Finally, we'll configure Telegram as the messaging gateway so you can interact with your personal AI assistant from anywhere.

• Open Telegram.
• Search for @BotFather (the verified account).
• Send:

/newbot

• Choose a bot name and username.
• Copy the bot token. You will use it later in the .env file.

Replace YourUsername with your Windows username:

mkdir C:\Users\YourUsername\hermes-data

The setup wizard will create the initial configuration files inside your hermes-data directory:

docker run -it --rm -v C:\Users\YourUsername\hermes-data:/opt/data nousresearch/hermes-agent:latest setup

Create a file named:

C:\Users\YourUsername\hermes-data\docker-compose.yml

Paste the following:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes

    restart: unless-stopped

    volumes:
      - C:\Users\KdeK\hermes-data:/opt/data

    ports:
      - "8642:8642"
      - "9119:9119"

    stdin_open: true
    tty: true

Create or edit:

C:\Users\YourUsername\hermes-data\.env

Example:

OPENROUTER_API_KEY=sk-or-v1-ABCDEFGabcdefg0123456789
TELEGRAM_BOT_TOKEN=0123456789:ABCDE123456--abcde123456-aABbCc
TELEGRAM_ALLOWED_USERS=123456789

Where:

1. OPENROUTER_API_KEY is obtained from OpenRouter.
2. TELEGRAM_BOT_TOKEN is obtained from BotFather.
3. TELEGRAM_ALLOWED_USERS is your Telegram numeric User ID.

cd C:\Users\YourUsername\hermes-data
docker compose up -d

Wait 10–20 seconds for Hermes to initialize.

View the logs:

docker logs -f hermes

A successful startup should display messages similar to:

Starting Hermes Gateway...
Connecting to telegram...
Connected to Telegram
Gateway running

Press Ctrl+C to stop viewing the logs. This does not stop Hermes.

Open your Telegram bot and send:

/sethome

Hermes may ask you to complete the initial pairing. Once complete, your private chat becomes the default Home channel.

To access the Hermes command-line interface:

docker exec -it hermes hermes

This connects to the running Hermes instance without stopping the Telegram gateway. Type /exit to exit the CLI.

After Windows starts:

1. Start Docker Desktop.
2. Wait until Docker Desktop reports Engine running.
3. Open PowerShell, and run these commands:

cd C:\Users\YourUsername\hermes-data
docker compose up -d

Hermes, the Dashboard, and the Telegram Gateway will start automatically.

You may simply shut down Windows. Docker will gracefully stop the Hermes container.

Alternatively:

docker compose down

To update Hermes to the latest version:

docker compose pull

Back up the following directory periodically:

C:\Users\YourUsername\hermes-data

This folder contains your configuration, memories, sessions, and database.