Hermes Agent Setup Guide

This guide provides a detailed, step-by-step setup for the Hermes Agent on Windows (via WSL), macOS, and Linux, and its integration with Telegram, enabling access to your autonomous AI assistant from your phone.

| 4 min read
This guide provides a detailed, step-by-step setup for the Hermes Agent on Windows (via WSL), macOS, and Linux, and its integration with Telegram, enabling access to your autonomous AI assistant from your phone.

Hermes Agent Setup Guide: Cross-Platform & Telegram Integration

Overview This tutorial provides a detailed, step-by-step guide on how to set up the official Hermes Agent by Nous Research from scratch on Windows (via WSL), macOS, and native Linux, and integrate it with Telegram. This allows you to access your autonomous, self-improving AI assistant anytime, anywhere from your phone.

Table of Contents - I. Environment Preparation

I. Environment Preparation

System Requirements Hermes relies heavily on Linux-based underlying process management. It natively supports macOS and major Linux distributions (Ubuntu, Debian, etc.). Windows users must use WSL2.

  • Windows users: Search for "Turn Windows features on or off", check Virtual Machine Platform and Windows Subsystem for Linux. Restart your PC, then run wsl --install in Command Prompt.
  • macOS users: Open Terminal. Run xcode-select --install to ensure command-line developer tools are installed.
  • Linux users: Open your standard terminal.

Environment Verification In your system’s terminal, ensure Python is ready (verify you are running a supported version, typically 3.8+): 

python3 --version

II. Hermes Agent Installation

Official One-Click Script Use the official script provided by Nous Research. This safely sets up the Python virtual environment and required build tools without polluting your global packages.

curl -fsSL [https://hermes-agent.nousresearch.com/install.sh](https://hermes-agent.nousresearch.com/install.sh) | bash

Note: During installation, if it asks whether to install ripgrep and build tools, type Y (these are required for the agent's file searching and skill execution capabilities).

Verify installation: ```bash hermes --version


---

## III. Basic Configuration

1. **Run the official setup wizard:** ```bash
   hermes setup
  1. Follow the prompts: * LLM Provider: It is highly recommended to use the Nous Portal or OpenRouter to access the official Hermes models (e.g., Hermes 3) or other top-tier reasoning models.
    • API Key: Enter your respective API Key.
    • Messaging Platform: Choose Skip — we will configure Telegram visually using the Web UI in the next steps.
  2. Config file location: Your base configuration is saved at ~/.hermes/config.yaml.

IV. Telegram Bot Creation

  1. In Telegram, search for @BotFather and send /newbot.
  2. Follow the prompts to set a display name and a unique username (must end in bot).
  3. Copy the generated Bot Token (format: 1234567890:ABCdef...).

Get your User ID: Search for @userinfobot in Telegram, send /start, and copy the numeric User ID shown. You will need this to secure your agent.

V. Service Startup & Web UI

While Hermes can be run entirely from the CLI, managing communication channels is significantly easier via the trending community dashboard, hermes-web-ui.

Web UI Installation: ```bash bash <(curl -fsSL https://raw.githubusercontent.com/EKKOLearnAI/hermes-web-ui/main/scripts/setup.sh)

*(If your terminal returns "hermes command not found", run `source ~/.bashrc` or `source ~/.zshrc` to refresh your environment variables, then rerun the script).*

**Start the Panel:** ```bash
hermes-web-ui start

Open your browser and navigate to http://localhost:8648.

VI. Telegram Integration (Web UI)

  1. In the Web UI, navigate to Gateway / Communication Settings.
  2. Enable the Telegram tab.
  3. Paste the Bot Token you obtained from BotFather.
  4. Save the configuration. The panel handles the Gateway restart automatically.

VII. User Pairing & Authorization

To prevent unauthorized access to your server via the Telegram bot, you must restrict access strictly to your Telegram account.

1. Create a backup of your environment file (Crucial Step): Before making manual changes, ensure you have a restoration point:

cp ~/.hermes/.env ~/.hermes/.env.backup

2. Set the User Whitelist: Append your Telegram User ID to the .env file to ensure only you can issue commands:

echo "TELEGRAM_ALLOWED_USERS=your_TG_user_ID" >> ~/.hermes/.env

3. Restart the Gateway Service: To ensure the new permissions take effect and clear any background conflicts:

pkill -f "hermes gateway" && hermes gateway run --replace &

VIII. Common Problem Solving

Q1: Web UI says "command not found" after installation. Your environment variables haven't refreshed. Run source ~/.bashrc (or source ~/.zshrc on macOS). If it still fails, execute it via the absolute path:
/home/yourusername/.hermes/node/bin/hermes-web-ui start

Q2: Bot goes offline when the terminal is closed. On Windows WSL, closing the terminal kills background processes. To keep Hermes online persistently, use a terminal multiplexer like tmux:

# Install tmux
sudo apt install tmux

# Start a new persistent session
tmux new -s hermes_session

# Start the UI/Gateway
hermes-web-ui start

# Detach from the session (leave it running in background)
# Press Ctrl+B, then release and press D

IX. Advanced Configuration

Hermes features persistent memory and auto-generated skills. To ensure SQLite full-text search and memory modules are properly initialized, verify your ~/.hermes/config.yaml contains: 

skills:
  enabled: true
  auto_load: true
memory:
  enabled: true
  storage: "sqlite"
  path: "~/.hermes/memory.db"

X. Maintenance & Updates

To keep the core Hermes Agent and its built-in tools up to date:

# Rerun the official install script to pull the latest binaries
curl -fsSL [https://hermes-agent.nousresearch.com/install.sh](https://hermes-agent.nousresearch.com/install.sh) | bash

# Refresh environment
source ~/.bashrc

Troubleshooting / Hard Reset: If the agent freezes during a complex task or you need to restart from a clean slate:

# Force-stop all Hermes processes
pkill -f "hermes"

# Restart the ecosystem via Web UI
hermes-web-ui start