Run Hermes as a Mattermost Bot

Mattermost is a strong fit for organizations that want team chat under their own administrative control. Hermes connects through a dedicated bot account and token. The safest deployment gives that bot only the channels, users, and tools required for its role.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/mattermost

Create a bounded bot identity

A Mattermost system administrator must first allow bot-account creation. Create a dedicated account such as hermes, copy the token once, and store it as a secret. Do not reuse a human personal access token. Add the bot only to channels where it has a defined purpose.

Collect stable Mattermost user IDs for operators who are allowed to issue commands. Display names can change and are weaker authorization identifiers. Decide whether public-channel messages require an explicit mention and how direct messages map to sessions.

Rollout checklist

Confirm bot accounts are enabled by a Mattermost administrator.
Create a dedicated Hermes bot account.
Store the token without adding it to source control or shell history.
Add the bot only to approved channels.
Record authorized user IDs, not just display names.
Run hermes gateway setup and select Mattermost.
Configure mention requirements for busy channels.
Select a home channel for scheduled delivery if needed.
Document which tools are allowed in shared sessions.

Protect session and thread boundaries

Test direct messages, channel posts, and threads as separate contexts. A reply must return to the originating channel and thread, and one team's context must not appear in another team's session. For sensitive workflows, use separate Hermes profiles or bot identities rather than relying only on conversational instructions.

Scheduled output should land in a fixed home channel with an understood audience. Avoid sending private research, credentials, or customer data into a general channel simply because it is convenient.

Common pitfalls

Using an administrator's token instead of a bot token.
Adding the bot to every channel before access behavior is tested.
Authorizing mutable usernames when stable user IDs are available.
Letting ordinary channel conversation trigger expensive agent runs.
Assuming a direct-message test proves thread routing.
Giving a shared chat session owner-level tools without approvals.

Verification steps

Start the gateway and confirm the Mattermost adapter authenticates as the bot identity.
Send a direct message from an allowed user and verify the response.
Post in an approved channel with and without a mention, according to policy.
Reply inside a thread and confirm Hermes answers in that same thread.
Test a nonmember channel and unauthorized user.
Restart the adapter and verify session mapping remains stable.
Review Mattermost audit logs and Hermes logs for excess channel access, token exposure, or cross-thread replies.