Agent Frameworks, CLI & DevTooling
Hermes Agent Setup Guide
Author
DW
Date Published
# 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)
- [II. Hermes Agent Installation](#ii-hermes-agent-installation)
- [III. Basic Configuration](#iii-basic-configuration)
- [IV. Telegram Bot Creation](#iv-telegram-bot-creation)
- [V. Service Startup & Web UI](#v-service-startup--web-ui)
- [VI. Telegram Integration (Web UI)](#vi-telegram-integration-web-ui)
- [VII. User Pairing & Authorization](#vii-user-pairing--authorization)
- [VIII. Common Problem Solving](#viii-common-problem-solving)
- [IX. Advanced Configuration](#ix-advanced-configuration)
- [X. Maintenance & Updates](#x-maintenance--updates)
---
## 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+):
```bash
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.
```bash
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
```
2. **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.
3. **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](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:
```bash
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:
```bash
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:
```bash
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`:
```bash
# 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:
```yaml
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:
```bash
# 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:
```bash
# Force-stop all Hermes processes
pkill -f "hermes"
# Restart the ecosystem via Web UI
hermes-web-ui start
```