Hermes Agent
Hermes Agent Mattermost: bot token, users and fixes
Updated 22 November 2026
Hermes Agent can sit in your Mattermost server as a bot, answering in direct messages and in channels. This page walks through the whole job: creating the bot, collecting the three values Hermes needs, configuring and starting the gateway, choosing how it behaves in channels and threads, and fixing the errors the documentation lists.
Facts come from the Hermes Agent 0.23.3 documentation, read on 22 November 2026: Mattermost setup, the messaging overview, the security guide and the environment variables reference.
What the Mattermost connection does
The documentation describes Mattermost as a self-hosted, open-source Slack alternative that you run on your own infrastructure. Hermes connects to it as a bot through Mattermost’s REST API (v4) and a WebSocket for real-time events, then runs each message through the normal Hermes pipeline, including tools, memory and reasoning. It handles text, file attachments, images and slash commands.
- No extra library. The adapter uses
aiohttp, which Hermes already depends on. - Self-hosted Mattermost. The documentation says it works with any self-hosted Mattermost instance, needs no Mattermost Cloud account or subscription, and works with Team Edition (free) and Enterprise Edition.
- Attachments. Inbound attachments are downloaded only for senders the gateway authorizes, and each is capped by
gateway.max_inbound_media_bytes.
Hermes runs as the gateway, a long-running process that holds the connection open. If you have not installed Hermes yet, start with how to install Hermes Agent.
Create the bot account in Mattermost
Bot accounts have to be switched on before you can make one, which needs a System Admin.
- Log in as a System Admin and go to System Console → Integrations → Bot Accounts. Set Enable Bot Account Creation to true and save. Without admin access, the documentation says to ask your administrator to enable bot accounts and create one for you.
- Open the menu at the top left → Integrations → Bot Accounts and click Add Bot Account.
- Fill in a username such as
hermes, a display name such as Hermes Agent, an optional description, and a role. The documentation says Member is sufficient. - Click Create Bot Account. Mattermost shows the bot token. Copy it straight away.
The token is displayed only once. If you lose it, you have to regenerate it from the bot account settings. Anyone holding it has full control of the bot, so keep it in a password manager and out of Git.
The documentation also mentions an alternative: a personal access token from Profile → Security → Personal Access Tokens → Create Token. That is useful if you want Hermes to post as your own user rather than as a separate bot user.
Add the bot to channels and find your user ID
The bot has to be a member of every channel where you want it to answer: open the channel, click the channel name, choose Add Members, search for the bot’s username, and add the bot to the channel. Once the gateway is running, authorised users can also message the bot directly without adding it to a channel.
Hermes decides who may use the bot from a Mattermost User ID, not a username. The documentation says the profile dialog does not show it, and gives four ways to get it:
- System Console (system admins): User Management → Users, then open your user. The ID is on the User Configuration page.
- Browser (any user): while logged in, open
https://your-mattermost-server/api/v4/users/mein a new tab. Theidfield is your User ID. - API with the bot token: look up your own username. The
idin the response is yours. - mmctl (system admins):
mmctl user list --allprints one line per user as<id>: <username> (<email>).
curl -s -H "Authorization: Bearer YOUR_BOT_TOKEN" https://your-mattermost-server/api/v4/users/username/YOUR_USERNAMEDo not call /api/v4/users/me with the bot token: that returns the bot’s ID, not yours. A User ID is a 26-character alphanumeric string, for example 3uo8dkh1p7g1mfk49ear5fzs5c. Your username, the part after the @, is a different thing and will not work.
You will also want a Channel ID later, for the home channel and for channel restrictions. Click the channel name and choose View Info; the ID is in the info panel.
Configure Hermes and start the gateway
The documentation recommends the guided setup. Run it in your terminal, choose Mattermost when asked, and paste the server URL, bot token and user ID:
hermes gateway setupFor manual setup, add these three lines to ~/.hermes/.env. Replace the example URL with your server address, *** with the token you copied, and the example user ID with your own Mattermost user ID.
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=***
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5cFor several people, separate the IDs with commas in MATTERMOST_ALLOWED_USERS. Use the full address with https:// and no trailing slash in MATTERMOST_URL. The setup wizard offers to start or restart the gateway when it finishes; if the gateway is still stopped, run:
hermes gatewayThe documentation says the bot should connect within a few seconds. From the account whose user ID you entered, send the bot a DM or @mention it in a channel you added it to. For something that keeps running after you close the terminal, it suggests running the gateway in the background or as a systemd service; the messaging overview lists hermes gateway install, hermes gateway start, hermes gateway stop and hermes gateway status for that. If you run Hermes in a container, see running Hermes Agent in Docker.
DMs, channels, threads and sessions
| Where | What Hermes does |
|---|---|
| Direct messages | Replies to every message from an authorised user, with no @mention needed. Each DM has its own session. |
| Public or private channels | Replies when you @mention it, and ignores messages without a mention. |
| Threads | With MATTERMOST_REPLY_MODE=thread it replies in a thread under your message, and the thread context stays isolated from the parent channel. |
| Shared channels | By default each user gets their own session history inside the channel. |
These optional settings in ~/.hermes/.env change that behaviour:
| Setting | What it does |
|---|---|
MATTERMOST_REPLY_MODE | off (the default) posts flat messages; thread replies under your original message, which keeps busy channels tidy. |
MATTERMOST_REQUIRE_MENTION | Default true. Set false to respond to all messages in channels. Authorised users can send DMs without a mention. |
MATTERMOST_FREE_RESPONSE_CHANNELS | Comma-separated channel IDs where the bot answers without an @mention, even when mentions are required. |
MATTERMOST_ALLOWED_CHANNELS | Enter channel IDs separated by commas. An empty value leaves channels unrestricted. With a non-empty list, the bot ignores messages in unlisted channels, even when mentioned. Authorised users can still send DMs. |
When the bot is mentioned, the mention is stripped from the message before Hermes processes it. The channel restriction can also be written in config.yaml; DMs are exempt from it, so authorised users can always reach the bot in a direct message:
mattermost:
allowed_channels:
- "abc123def456ghi789jkl012mno"
- "xyz987uvw654rst321opq098nml"An empty or unset list means no restriction. A non-empty list is checked first: a channel not on it is dropped before the mention rules or MATTERMOST_FREE_RESPONSE_CHANNELS are consulted.
Session isolation is controlled by group_sessions_per_user in ~/.hermes/config.yaml, which is true by default:
group_sessions_per_user: trueSet it to false only if you want one shared conversation for the whole channel. The documentation lists the costs: users share context growth and token costs, one person’s long tool-heavy task can bloat everyone else’s context, and one person’s run in progress can interrupt another person’s follow-up.
You can also give a channel its own instructions. In ~/.hermes/config.yaml, put channel_prompts under mattermost and map each channel ID to its prompt. Hermes applies it on every turn without saving it to the transcript, so a change takes effect immediately. For example, a research channel can use the instruction “Focus on academic sources, citations, and concise synthesis.”
Home channel and scheduled messages
The home channel is where the bot sends messages you did not just ask for, such as cron job output, reminders and notifications. There are two ways to set it. In the channel you want, type /sethome; the bot must be a member and your account must be allowed to run the command there. Or open the channel name, choose View Info, copy the Channel ID and use it in place of the example ID in ~/.hermes/.env:
MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mnFor how to create the jobs themselves, see Hermes Agent cron jobs. The messaging overview also says the gateway can post a one-off “the agent is back” or “the agent was interrupted” message to a platform’s home channel when it restarts, and that this is controlled per platform by the gateway_restart_notification flag in config.yaml, which defaults to true.
Who is allowed to talk to it
Set MATTERMOST_ALLOWED_USERS to the Mattermost user IDs of people you trust. By default, the gateway denies access to anyone who is neither on an applicable allowlist nor approved through DM pairing. Authorised users can use the agent’s tools and access the system.
- Allow everyone.
MATTERMOST_ALLOW_ALL_USERSlets any Mattermost user trigger the bot. The environment variables reference labels it for development only. - Pairing. The messaging overview describes a DM pairing alternative to allowlists: when DM pairing is enabled, an unknown user can send the bot a direct message to receive a one-time code. To approve someone you trust, run
hermes pairing approve <platform> <code>in your terminal, replacing<platform>withmattermostand<code>with that user’s code. Codes expire after one hour. The Mattermost page itself documents only the allowlist, so use the allowlist if you want the documented route for this platform. - Other bots. Posts from Mattermost bot accounts are recognised on their own. Bots using personal access tokens are not, so list their user IDs in
MATTERMOST_BOT_USERS(orbot_usersundermattermostinconfig.yaml). Bot senders are admitted only through the platform’sMATTERMOST_ALLOW_BOTSsetting, which the source shows asallormentions; set it only when bot-to-bot messages are intended. A loop guard,gateway.bot_loop_guard, ends runaway exchanges.
The full picture is in the security guide. Treat the bot token like a password.
Troubleshooting
The bot does not respond. Check that the bot belongs to the channel. If you use MATTERMOST_ALLOWED_USERS, check that it contains your user ID. Add the bot through the channel’s Add Members, check the ID, and restart the gateway. If a channel list is set, check the channel is on it too. In a channel, remember the bot needs an @mention unless you changed that.
403 Forbidden. The token is invalid or the bot cannot post in the channel. Check MATTERMOST_TOKEN, make sure the bot account has not been deactivated, and confirm it has been added to the channel. With a personal access token, your account needs the required permissions.
“Failed to authenticate” on startup. The token or server URL is wrong. Check that MATTERMOST_URL includes https:// and has no trailing slash, then test the token directly:
curl -H "Authorization: Bearer YOUR_TOKEN" https://your-server/api/v4/users/meUse your server address in place of https://your-server and your token in place of YOUR_TOKEN. A valid bot token returns the bot’s details; a valid personal access token returns your own. If authentication fails with the address confirmed, regenerate the token and update MATTERMOST_TOKEN.
The bot is offline. The gateway is not running or failed to connect. Check that hermes gateway is running and read its output for errors. The documentation names a wrong URL, an expired token and an unreachable Mattermost server as the usual suspects.
“User not allowed” or the bot ignores you. If you use MATTERMOST_ALLOWED_USERS, check that it contains your 26-character user ID, not your @username. If it is missing, add it in ~/.hermes/.env and restart the gateway.
WebSocket disconnects or reconnect loops. Causes listed are network instability, Mattermost server restarts, and firewall or proxy problems. The adapter reconnects automatically with exponential backoff from 2 seconds up to 60. Reverse proxies such as nginx or Apache need WebSocket upgrade headers, and no firewall should block WebSocket connections to the Mattermost server. For nginx the documentation gives:
location /api/v4/websocket {
proxy_pass http://mattermost-backend;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 600s;
}The platform stays paused. The messaging overview says each adapter has a circuit breaker: after repeated retryable failures the adapter is paused and does not resume by itself. Check the gateway log, which is ~/.hermes/logs/gateway.log or the service log, and /platform list for the reason, and, once the server is healthy, use a connected Hermes CLI session or another working chat. Enter /platform list to find the paused adapter’s name, then use /platform resume <name>, replacing <name> with the listed name. Restarting the gateway is covered in the gateway restart guide.
Mattermost on ReadyHermes
Mattermost is not offered in the ReadyHermes Channels panel today, and connecting it on a ReadyHermes assistant is not something we have tested or support. We do not suggest a workaround.
The Channels panel offers Telegram, WhatsApp, Discord, WeChat, Lark and the Hermes Desktop connection. If one of those fits your team, see Telegram, WhatsApp, Discord or WeChat. If Mattermost is a requirement, run Hermes yourself using the steps above. To compare the two routes, read self-hosting vs managed hosting.
ReadyHermes plans start from US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month and a 1-hour free trial.
Questions
How do I connect Hermes Agent to Mattermost?
Enable bot accounts in the System Console, create the bot, copy its token, and find your own Mattermost user ID. Run hermes gateway setup, choose Mattermost, and enter your server URL, token, and user ID. For manual setup, enter those values in ~/.hermes/.env as MATTERMOST_URL, MATTERMOST_TOKEN, and MATTERMOST_ALLOWED_USERS. If the gateway is still stopped after setup, start it with hermes gateway.
Does Hermes need an @mention in Mattermost channels?
In channels, yes by default: it replies when mentioned and ignores other messages. In direct messages, authorised users can chat without a mention. Set MATTERMOST_REQUIRE_MENTION to false, or list channel IDs in MATTERMOST_FREE_RESPONSE_CHANNELS, to let it answer without a mention.
Why does the Hermes bot ignore me in Mattermost?
For an allowlist setup, check that MATTERMOST_ALLOWED_USERS in ~/.hermes/.env contains your 26-character Mattermost user ID, not your @username. Restart the gateway after correcting it. If DMs work but a channel is silent, add the bot through Add Members, check any channel restrictions, and @mention the bot if mentions are required.
Can Hermes reply in threads on Mattermost?
Yes. Set MATTERMOST_REPLY_MODE=thread and Hermes replies in a thread under your message, with the thread context kept separate from the channel. The default, off, posts flat messages.
Is Mattermost available on ReadyHermes?
No. The ReadyHermes Channels panel offers Telegram, WhatsApp, Discord, WeChat, Lark and the Hermes Desktop connection. We have not tested connecting Mattermost on a ReadyHermes assistant, and we do not currently support that connection. To use Mattermost, run Hermes yourself.