Wiki · Start here
Telegram and Discord
So the agent answers from your phone — and nobody else can run anything with it.
What you need
| Item | What it is for |
|---|---|
| A running agent on a server | The gateway is part of the agent — once it runs, you just switch the gateway on |
| A bot on Telegram or Discord | Free to create, a two-minute job (steps below) |
| Your numeric ID | Not your name or handle. The number is how the agent knows it is you — and how nobody else can use your bot |
Pick one platform, or both. Most people start with Telegram — it is the fastest route to your phone.
Telegram — step by step
- Create the bot. Message @BotFather with
/newbot, answer the name questions, and it sends you a token. Treat it like a password and never share it. - Find your numeric ID. Message @userinfobot and it replies
with your ID (e.g.
123456789). - Configure the agent. The easiest way is the wizard, which asks for the token and your ID
and writes everything for you:
$ hermes gateway setupOr do it by hand — add two lines to
~/.hermes/.env:# ~/.hermes/.env TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ TELEGRAM_ALLOWED_USERS=123456789 # separate several IDs with a comma - Start the gateway and check it.
$ hermes gateway start $ hermes gateway status
- Send the bot a message. It replies within seconds.
You can add the bot to a group, but by default Telegram will not let it read ordinary
messages (privacy protection) — it only sees commands and @yourbot mentions. For group use, switch
Group Privacy off in @BotFather.
What else it does: send and receive files and photos, transcribe voice messages, and deliver the
output of scheduled jobs to a chosen conversation (TELEGRAM_HOME_CHANNEL).
Discord — step by step
- Create an application and a bot. At discord.com/developers/applications choose New Application, then Bot in the left menu.
- Enable message reading. Turn on Message Content Intent (a privileged permission). Without it the bot cannot see messages and looks dead.
- Copy the token (Reset Token) — it is shown once, so save it immediately.
- Invite the bot to your server. Generate an invite link in the Installation tab with the read/send messages and attach files permissions.
- Find your ID. Enable Developer Mode (User Settings → Advanced), then right-click your name and choose Copy User ID.
- Configure and start the agent — same as Telegram:
# wizard (recommended) — pick Discord $ hermes gateway setup # or by hand in ~/.hermes/.env DISCORD_BOT_TOKEN=your-token DISCORD_ALLOWED_USERS=284102345871466496 # separate several IDs with a comma # and start it $ hermes gateway start
Mention the bot in a channel (@yourbot) — in normal channels it only reacts to mentions so it
does not interrupt the conversation. In a direct message it answers anything. It also supports slash commands
directly in Discord (for example status or switching the model).
You can split people into admins (all commands) and regular users
(only the commands you allow) using allow_admin_from and user_allowed_commands. Handy for a
family or a team — everyone else gets access only to what you grant.
Who can talk to the bot
| Rule | Why |
|---|---|
| The token is a password | Whoever gets it controls your bot. Never paste it into a chat or a repository. If you leak it, revoke it immediately (Reset Token in @BotFather / the Developer Portal) |
| The allow list | The bot only answers IDs on the list. A stranger who finds your bot gets no reply — and above all runs nothing |
| An empty list is an open door | Leave the list empty (or the "allow everyone" switch on Discord) and anyone can use your bot. Always add your own ID |
| One running gateway per token | Two agents sharing a token fight over messages and steal each other's replies |
When it does not work
| Symptom | Usual cause and what to do |
|---|---|
| The bot is silent | The gateway is not running — check hermes gateway status and start it with hermes gateway start |
| It runs but ignores me | Your ID is not on the list, or the wrong number is there (verify with @userinfobot). A common mistake is pasting a username instead of the number |
| Silent in groups, works in DMs | Group Privacy — turn it off in @BotFather, or address the bot with @yourbot |
| Looks dead on Discord | Message Content Intent is off, or the invite link was generated without the needed permissions |
| Answered once, then nothing | Most likely a second agent copy with the same token, or no model credit (see choosing a model) |
| It disappeared after a reboot | The gateway has to run as a service (systemd) to start by itself. The deployment docs cover it |
Tips from running it
| Tip | Why |
|---|---|
| Start with Telegram | Two minutes of work and it works from your phone, no computer needed |
| Discord suits a group | Channels, mentions and separate permissions — the agent does not disturb other conversations |
| Have long output sent as a file | The agent can attach a file (a listing or a table), which reads better in a chat than a wall of text |
| Check the status after every change | hermes gateway status tells you whether the gateway runs and which platform is connected |
| Try a voice message | On Telegram you can dictate the task instead of typing it |