===== Hermes Installation on Windows 11 =====

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.

=== #1 Create a Telegram Bot ===

  * 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.

=== #2 Create the Hermes Data Folder ===

Replace YourUsername with your Windows username:

  mkdir C:\Users\YourUsername\hermes-data

=== #3 Run the setup wizard ===

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

=== #4 Create docker-compose.yml ===

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

=== #5 Configure the Environment Variables ===

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:

  - OPENROUTER_API_KEY is obtained from OpenRouter.
  - TELEGRAM_BOT_TOKEN is obtained from BotFather.
  - TELEGRAM_ALLOWED_USERS is your Telegram numeric User ID.

=== #6 Start Hermes ===

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

Wait 10–20 seconds for Hermes to initialize.

=== #7 Verify Hermes ===

View the logs for Gateway & Dashboard:

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

=== #8 Pair Telegram ===

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.

=== #9 Open the Hermes CLI (Optional) ===

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.

----

=== Daily Startup ===

After Windows starts:

  - Start Docker Desktop.
  - Wait until Docker Desktop reports Engine running.
  - 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

=== Daily Shutdown ===

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

Alternatively:

  docker compose down

=== Updating Hermes ===

To update Hermes to the latest version:

  docker compose pull

=== Backup ===

Back up the following directory periodically:

  C:\Users\YourUsername\hermes-data

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