Step-by-Step Guide

4 Distinct Telegram Channels on One Hermes Agent

Two production-ready approaches — from zero to fully running in under 30 minutes.

⚡

Choose Your Approach First

Approach A — DM Topics ✓ Recommended

One bot token, one gateway process. Four topics inside your existing DM with the bot. Best for personal multi-project workflows. Lowest complexity.

Approach B — Multiple Bot Instances

Four separate Hermes gateway processes, each with its own bot token. True process-level isolation. Best for multi-tenant or team deployments.

A Approach A — DM Topics (Single Bot)

Get Your Telegram User ID

You need your numeric Telegram user ID to configure the DM topics. This is not your @username — it's a permanent number like 123456789.

Step 1: Open Telegram

1. Open Telegram app or web
2. Search for @userinfobot
3. Send any message (e.g. "hi")
4. The bot replies with your user ID:
   "Your Telegram ID: 123456789"
5. Copy that number — you'll use it as chat_id

Alternative bots: @get_id_bot or @idbot all work the same way.

Create a Telegram Bot (or Use Existing)

You need one bot token total. If you already have one configured in ~/.hermes/.env, skip this step.

Step 1: Message @BotFather

1. Open Telegram → search @BotFather
2. Send /newbot
3. Enter a Display name: e.g. "My Hermes Assistant"
4. Enter a Username (must end in bot): e.g. "myhermes_bot"
5. BotFather replies with your token:

   Use this token to access the HTTP API:
   7123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

6. COPY THE TOKEN NOW — it won't be shown again

Step 2: Add token to ~/.hermes/.env

TELEGRAM_BOT_TOKEN=7123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

⚠️ Keep this secret! Anyone with the token can control your bot. If it leaks, run /revoke in @BotFather to get a new one immediately.

Enable Topics Mode in Your Telegram Client

This is a client-side setting the user must enable. Hermes cannot do this programmatically.

On iOS/Android

1. Open your private chat with the Hermes bot
2. Tap the bot's name at the TOP of the chat (opens chat info)
3. Look for "Topics" toggle
4. Enable it (turn it ON)
5. Go back to the chat — you'll now see topic tabs at the top

On Telegram Desktop / Web

1. Open your private chat with the Hermes bot
2. Click the bot name at the top (opens sidebar)
3. Click the pencil/edit icon near the bot name
4. Toggle "Enable Topics"
5. Close — topic tabs appear at the top of the chat

Without this step: Hermes will log The chat is not a forum on startup and skip topic creation. The bot still works — just without topic isolation.

Configure DM Topics in config.yaml

Replace 123456789 with your Telegram user ID from Step A1. These are your 4 channel names — name them however makes sense for your workflow.

~/.hermes/config.yaml — paste this entire section

platforms:
  telegram:
    enabled: true
    token: "$TELEGRAM_BOT_TOKEN"
    reply_to_mode: "first"
    home_channel:
      platform: telegram
      chat_id: 123456789   # ← REPLACE with YOUR user ID
      name: "Home"
    extra:
      dm_topics:
        - chat_id: 123456789   # ← REPLACE with YOUR user ID
          topics:
            - name: "General"
              icon_color: 7322096
            - name: "Alice"
              icon_color: 9367192
            - name: "Bob"
              icon_color: 16766590
            - name: "Charlie"
              icon_color: 11134880

Adding Skill Binding (Optional)

Each topic can auto-load a specific skill when sessions reset. Useful for project-specific tools:

Skill binding example

            - name: "Research"
              icon_color: 9367192
              skill: "arxiv"          # arxiv skill loads automatically
            - name: "Code"
              icon_color: 16766590
              skill: "software-development"  # coding skill auto-loaded

Icon Colors Reference

Color	Hex Code	Preview
Blue	`7322096`
Sky Blue	`9367192`
Green	`16766590`
Purple	`11134880`
Orange	`16486984`
Pink	`11281461`

Set Allowed Users

Add your user ID to ~/.hermes/.env so only you can access the bot:

~/.hermes/.env

TELEGRAM_BOT_TOKEN=7123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789  # REPLACE with your user ID
TELEGRAM_HOME_CHANNEL=123456789   # Default delivery target for cron jobs

Multiple users: Separate with commas — TELEGRAM_ALLOWED_USERS=111111,222222,333333. For team onboarding, use the DM Pairing flow described in the Team Telegram Assistant guide.

Start the Gateway

Quick test

hermes gateway

You should see output like:

Expected startup output

[Gateway] Starting Hermes Gateway...
[Telegram] Connected to Telegram (polling mode)
[Telegram] DM topic loaded from config: 123456789:General -> thread_id=1
[Telegram] DM topic loaded from config: 123456789:Alice -> thread_id=2
[Telegram] DM topic loaded from config: 123456789:Bob -> thread_id=3
[Telegram] DM topic loaded from config: 123456789:Charlie -> thread_id=4
[Gateway] Connected to Telegram (polling mode)
[Gateway] Cron scheduler started (tick every 60s)

First run (topics don't exist yet)

[Telegram] Created DM topic 'General' in chat 123456789 -> thread_id=1
[Telegram] Created DM topic 'Alice' in chat 123456789 -> thread_id=2
[Telegram] Created DM topic 'Bob' in chat 123456789 -> thread_id=3
[Telegram] Created DM topic 'Charlie' in chat 123456789 -> thread_id=4
[Telegram] Persisted thread_id=1 for topic 'General' in config.yaml
[Telegram] Persisted thread_id=2 for topic 'Alice' in config.yaml
...

✓ Topics auto-persist! The thread_id values are written back to config.yaml automatically — subsequent restarts skip topic creation entirely.

For Production: Install as a System Service

Linux systemd (runs in background, survives reboot)

# Install as a user-level service
hermes gateway install

# Install as a system-wide service (Linux server)
sudo hermes gateway install --system

# Start / stop / check status
hermes gateway start
hermes gateway stop
hermes gateway status

# View live logs
journalctl --user -u hermes-gateway -f

Verify — Open Your DM and Use the Topics

Open Telegram, find your bot, and you should now see topic tabs at the top of the chat:

What you should see in the Telegram app

┌──────────────────────────────────────────┐
│  🤖 My Hermes Assistant                    │
├──────────────────────────────────────────┤
│  [ General ] [ Alice ] [ Bob ] [ Charlie ] │  ← Topic tabs
│                                           │
│  📌 Click any tab to open an isolated     │
│     conversation thread                   │
│                                           │
│  Each topic maintains its own:             │
│  • Conversation history                   │
│  • Session context                        │
│  • Skill bindings                         │
│  • Memory                                 │
└──────────────────────────────────────────┘

✓ You're done! Send a message in any topic — it gets its own isolated session. Topics persist across restarts.

B Approach B — Multiple Bot Instances

Create 4 Bot Tokens via @BotFather

Each user (or user group) gets their own Telegram bot. Repeat for each:

Repeat 4 times — one per bot

For each bot, message @BotFather:
1. Send /newbot
2. Follow prompts to name it
3. Copy the token from the reply
4. Store it in a secure place (you'll add to each profile below)

Expected tokens:
  Alice bot:  712345678:AAalice...
  Bob bot:    712345679:BBbob...
  Charlie bot: 712345680:CCcharlie...
  Team bot:   712345681:DDteam...

Create Hermes Profiles for Each Instance

Hermes supports profiles — each profile has its own config.yaml, .env, sessions, and gateway process. This is how we run 4 isolated instances.

Create profile directories

mkdir -p ~/.hermes/profiles/alice/.env
mkdir -p ~/.hermes/profiles/bob/.env
mkdir -p ~/.hermes/profiles/charlie/.env
mkdir -p ~/.hermes/profiles/team/.env

~/.hermes/profiles/alice/.env

# Copy shared credentials from main .env
OPENAI_API_KEY=sk-...
MINIMAX_API_KEY=sk-...

# Alice's unique bot
TELEGRAM_BOT_TOKEN=712345678:AAalice...
TELEGRAM_ALLOWED_USERS=111111   # Alice's user ID
TELEGRAM_HOME_CHANNEL=111111

~/.hermes/profiles/bob/.env

OPENAI_API_KEY=sk-...
MINIMAX_API_KEY=sk-...
TELEGRAM_BOT_TOKEN=712345679:BBbob...
TELEGRAM_ALLOWED_USERS=222222   # Bob's user ID
TELEGRAM_HOME_CHANNEL=222222

Key insight: Each profile can use different AI models, different skill sets, different SOUL.md personalities, and different allowed users. Full customization per user.

Create Profile-Specific config.yaml Files

~/.hermes/profiles/alice/config.yaml

model:
  default: minimax-m2.7
  provider: opencode-go

group_sessions_per_user: true

~/.hermes/profiles/bob/config.yaml

model:
  default: anthropic/claude-sonnet-4-7
  provider: openrouter

group_sessions_per_user: true

Per-user customization: Alice gets MiniMax M2.7. Bob gets Claude Sonnet 4 via OpenRouter. Charlie gets a custom model. Each profile is completely independent.

Create systemd Service Files

Create one systemd service per profile so all 4 gateway instances start on boot and run as separate processes:

~/.config/systemd/user/hermes-alice.service

[Unit]
Description=Hermes Gateway — Alice
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/hermes gateway --profile alice
Restart=always
RestartSec=10
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="HERMES_PROFILE=alice"

[Install]
WantedBy=default.target

~/.config/systemd/user/hermes-bob.service

[Unit]
Description=Hermes Gateway — Bob
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/hermes gateway --profile bob
Restart=always
RestartSec=10
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="HERMES_PROFILE=bob"

[Install]
WantedBy=default.target

Repeat for charlie and team profiles. Then:

Enable and start all 4 services

# Reload systemd to pick up new service files
systemctl --user daemon-reload

# Enable all 4 services (start on boot)
systemctl --user enable hermes-alice
systemctl --user enable hermes-bob
systemctl --user enable hermes-charlie
systemctl --user enable hermes-team

# Start all 4 services
systemctl --user start hermes-alice
systemctl --user start hermes-bob
systemctl --user start hermes-charlie
systemctl --user start hermes-team

# Check status
systemctl --user status hermes-alice
systemctl --user status hermes-bob

# View logs for a specific instance
journalctl --user -u hermes-alice -f

For servers without systemd (or for simpler management), use tmux or screen sessions, or a process manager like supervisord.

Verify All 4 Instances Are Running

Check status

# List all running Hermes processes
ps aux | grep "hermes gateway" | grep -v grep

# Expected output (4 processes):
alice   hermes gateway --profile alice     ← @AliceAssistantBot
bob     hermes gateway --profile bob       ← @BobAssistantBot
charliehermes gateway --profile charlie  ← @CharlieAssistantBot
team    hermes gateway --profile team     ← @TeamAssistantBot

# Check gateway logs
tail -f ~/.hermes/profiles/alice/logs/gateway.log
tail -f ~/.hermes/profiles/bob/logs/gateway.log

✓ Test each bot: Open Telegram, find each bot by its username, send a message. Each should respond independently with its own session history.

Quick Reference — DM Topics (Approach A)

Topic Name	Session Key	Purpose
General	`telegram:dm:123456789:1`	Default / misc tasks
Alice	`telegram:dm:123456789:2`	Alice's workspace
Bob	`telegram:dm:123456789:3`	Bob's workspace
Charlie	`telegram:dm:123456789:4`	Charlie's workspace

Quick Reference — Multi-Bot (Approach B)

Profile	Bot Username	User(s)	Model
alice	@AliceAssistantBot	Alice (111111)	MiniMax M2.7
bob	@BobAssistantBot	Bob (222222)	Claude Sonnet 4
charlie	@CharlieAssistantBot	Charlie (333333)	MiniMax M2.7
team	@TeamAssistantBot	Team (444444, 555555)	MiniMax M2.7