The Telegram gateway is how most users access Hermes — from your phone, anywhere, for an always-on personal agent. Here is how to set it up and common fixes for issues. Unlike ChatGPT or Claude, Hermes runs 24/7 on your own server.
Why Telegram
- Mobile access from anywhere
- Reliable push notifications
- Voice message support
- Media handling (images, documents)
- Group chat support with access controls
The gateway runs as a background service via the multi-platform gateway. When you message the bot, the gateway forwards to Hermes and replies back.
Step-by-Step Setup
1. Create Your Bot
- Open Telegram, message @BotFather
- Send
/newbot - Choose a display name (e.g., "My Hermes")
- Choose a username ending in bot (e.g., myhermes_agent_bot)
- BotFather replies with your token — copy it
Your token looks like: 1234567890:ABCdefGhijklMNOPqrstuvwXYZ
2. Get Your User ID
- Message @userinfobot on Telegram
- It replies with your numeric ID (e.g.,
123456789)
3. Configure Hermes
hermes gateway setup
Select Telegram, paste your bot token, enter your user ID for allowed_user_ids.
Allowed user IDs can be a list for team use:
telegram:
allowed_user_ids:
- 123456789
- 987654321
4. Start the Gateway
hermes gateway start
Message your bot. You should get a response.
Multi-User Setup
For teams, configure multiple user IDs in gateway config. Each user gets their own conversation thread with shared memory.
For completely separate instances, run multiple Hermes profiles:
hermes profile create dev # creates separate profile
hermes profile use dev
hermes gateway start
Use Cases
Mobile Access
Run Hermes on a VPS, access from your phone. Check on servers, run tasks, get notifications — anywhere.
Team Bot
Shared agent for the team. Configure multiple allowed users. All conversations share memory and skills.
Channel-Based Access
Add the bot to a group, configure which group IDs (not user IDs) can access.
Common Issues
Bot Not Responding
- Check gateway is running:
hermes gateway status - Verify your user ID is in
allowed_user_ids - Restart gateway:
hermes gateway restart - Check logs:
hermes gateway logs
"Unauthorized user triggered thread"
Fixed in PR #4373. Update to latest Hermes version.
Token Overhead (15-20k vs 6-8k)
The gateway loads extra context. In recent versions, make sure it starts from your home directory, not the repo directory.
Bot Can't See Messages
- Bot must be admin or have "Read Messages" permission in group
- Or use group ID instead of user IDs
Security Note
Telegram messages transit through Telegram's servers — not end-to-end encrypted. For sensitive work, consider:
- Running Hermes locally and only accessing via CLI for sensitive tasks
- Using Signal instead (also supported)
- Using Ollama for fully offline operation
FAQ
Can I use Telegram and Discord on the same Hermes?
Yes — multiple gateways can run simultaneously. hermes gateway setup configures each.
Does Telegram keep conversation history? Yes, within the Telegram chat. Hermes sessions are separate threads.