Hermes Agent + Mattermost: Self-Hosted Team Chat Gateway Setup Guide

This guide covers how to connect Hermes Agent to Mattermost, turning your self-hosted chat platform into a gateway for code queries, ops tasks, research, and incident support. It is written for self-hosted teams that already run Mattermost and want to give team members access to Hermes tools, skills, and MCP servers without requiring terminal access.

What You Need

Before starting, ensure the following prerequisites are in place:

• A running Mattermost instance (self-hosted, any version supported by your deployment).
• Administrator access to Mattermost to create or configure a bot account.
• Hermes Agent installed and configured with at least one active profile. The profile must contain the credentials that the gateway will use to authenticate with Mattermost.
• The hermes CLI available on the machine that will run the gateway. The gateway is a long-running process that must stay active to receive and respond to messages.
• A test user or private channel for the initial smoke test. Do not start with a production or team-wide room.

Understanding the Hermes Mattermost Integration

Mattermost is a good match for self-hosted teams that want Hermes in the same private chat environment as engineering and operations conversations. According to the official documentation, Mattermost should be treated as a human-facing gateway, not the whole automation system. The chat message starts the request, but Hermes can still use files, terminal tools, MCP servers, web search, cron history, GitHub, Linear, Notion, and project-specific skills to do the real work.

What Mattermost Is Good For

The integration is designed for specific use cases where chat is the most natural interface:

• Operational alerts and status reports: Reach people without opening a terminal. A team member can ask for a status summary directly in the channel.
• Approval workflows: Hermes drafts the action, but a human confirms it in chat before anything is sent, deployed, or edited.
• Project-specific agents: Narrow channel boundaries allow different agents for different projects, rather than one global bot everywhere.
• Incident, support, or operations requests: Send a request from the chat app your team already uses.
• Cron reports, deployment notes, research summaries, or approval prompts: Receive these in a familiar channel without checking email or a separate dashboard.

Key Features

The official documentation lists these features for the Mattermost gateway:

• Mattermost gateway access for chat-based Hermes requests.
• Allowlisted users, rooms, groups, or contacts before broader rollout.
• Tool-backed answers using the same Hermes skills and MCP servers available from the CLI.
• Delivery target for cron reports, incident summaries, approval prompts, and project updates.
• Profile and credential boundaries so each channel can be scoped to the right trust level.
• Private smoke-test flow before enabling production rooms or free-response behavior.

Setup Path

The official documentation provides a six-step setup path. Each step is explained in detail below.

Step 1: Create or Configure the Mattermost Bot Account

You need a bot account in Mattermost that Hermes will use to post messages and read mentions. The exact steps depend on your Mattermost version, but the general process is:

1. Go to System Console > Integrations > Bot Accounts.
2. Enable bot account creation if it is not already enabled.
3. Create a new bot account with a username and display name. The username will be used to mention the bot in channels.
4. Assign the bot to a role with the minimum permissions needed. The official documentation does not specify exact permissions, but the bot needs to read messages that mention it and post messages in channels it is a member of.
5. Generate an access token for the bot. Save this token securely; you will need it in the next step.

Step 2: Store the Token or Credentials in the Active Hermes Profile

Do not store the Mattermost bot token in source control, a shared note, or any location that is not the active Hermes profile. The official documentation is explicit: credentials must be stored in the active Hermes profile environment.

To store the token, set it as an environment variable in your Hermes profile configuration. The exact variable name is not specified in the source, but typical Hermes gateway adapters use a variable like MATTERMOST_BOT_TOKEN or similar. Check your Hermes profile documentation or the output of hermes gateway setup for the required variable name.

For example, if your profile uses a .env file, add:

MATTERMOST_BOT_TOKEN=your_bot_token_here

If you are using a YAML or JSON profile configuration, add the token under a credentials or environment section. The key point is that the token must be accessible to the gateway process at runtime.

Step 3: Run hermes gateway setup and Enable the Platform Adapter

Run the following command:

hermes gateway setup

This command will guide you through the gateway configuration. When prompted, select Mattermost as the platform adapter to enable. The official documentation says to enable only the platform you are testing. If you have other adapters (Slack, Discord, etc.), disable them for now to avoid confusion during the smoke test.

The setup command will likely ask for the Mattermost server URL, the bot token, and possibly a webhook URL or other connection details. Provide the information from Step 1 and Step 2.

Step 4: Restrict Allowed Users, Rooms, Groups, or Contacts Before the First Test

Before starting the gateway, configure allowlisting. The official documentation recommends restricting who can talk to the bot before the first test. This is a critical safety measure.

During hermes gateway setup or in the gateway configuration file, specify:

• Allowed users: A list of Mattermost user IDs or usernames that are permitted to interact with the bot.
• Allowed rooms: A list of channel IDs or names where the bot is allowed to respond.
• Allowed groups: A list of group IDs if you want to allow entire teams.
• Allowed contacts: A list of direct message contacts.

Start with one private user or test room. The official documentation says: "Allowlist one private user or test room before adding team-wide rooms."

Step 5: Restart the Gateway and Send One Harmless Private Test Message

After configuration, restart the gateway:

hermes gateway restart

Or if you are running it as a service, restart the service. Then send a harmless prompt to the bot in a private message. The official documentation suggests this exact prompt:

reply with the active profile and enabled platform name.

This test confirms that:

• The gateway is running and connected to Mattermost.
• The bot can receive and respond to messages.
• The correct Hermes profile is active.
• The Mattermost platform adapter is enabled.

If you get a response, the smoke test passes. If not, see the Troubleshooting section below.

Step 6: After the Smoke Test, Connect Project Skills, Cron Reports, MCP Tools, or Team Rooms

Only after the smoke test passes should you expand the bot's capabilities. The official documentation says: "Only after the smoke test, connect project skills, cron reports, MCP tools, or team rooms."

Decide whether the channel can use:

• Tools (file access, terminal commands, etc.)
• Cron reports (scheduled summaries)
• File access (reading and writing files)
• Project-specific skills (custom skills defined for a project)

Add team rooms one at a time, testing each after adding it. The official documentation warns: "Do not start with file edits, deploys, purchases, or external sends."