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-cli:
  image: nousresearch/hermes-agent:latest
  container_name: hermes-cli
  stdin_open: true
  tty: true
  volumes:
    - C:\Users\YourUsername\hermes-data:/opt/data
hermes-gateway:
  image: nousresearch/hermes-agent:latest
  container_name: hermes-gateway
  command: gateway run
  restart: unless-stopped
  volumes:
    - C:\Users\YourUsername\hermes-data:/opt/data
hermes-dashboard:
  image: nousresearch/hermes-agent:latest
  container_name: hermes-dashboard
  command: dashboard --host 0.0.0.0 --port 9119 --no-open
  restart: unless-stopped
  ports:
    - "9119:9119"
  volumes:
    - C:\Users\YourUsername\hermes-data:/opt/data

Create a file named:

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

Example of the values:

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 for Gateway & Dashboard:

docker logs hermes-gateway --tail 10
docker logs hermes-dashboard --tail 10

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

A successful startup should display messages similar to:

PS C:\Users\YourUsername\hermes-data> docker compose up -d
[+] up 4/4
 ✔ Network hermes-data_default Created                                                                              0.0s
 ✔ Container hermes-gateway    Started                                                                              0.6s
 ✔ Container hermes-cli        Started                                                                              0.6s
 ✔ Container hermes-dashboard  Started                                                                              0.8s

Hermes, the Dashboard, and the Telegram Gateway will start automatically. Access the dashboard via this URL: http://localhost:9119

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.