Integration
Hermes Agent Matrix Setup: Connect Rooms, Threads, and E2EE
Set up Hermes Agent with Matrix or Element using a dedicated account, homeserver token, user and room allowlists, threads, session isolation, and optional E2EE.
Quick answer
Create a dedicated Matrix account, get an access token, run hermes gateway setup, and restrict both MATRIX_ALLOWED_USERS and MATRIX_ALLOWED_ROOMS before inviting the bot. DMs respond without a mention; rooms require @mention by default; real Matrix threads keep their own context. Enable MATRIX_E2EE_MODE=required only after the encryption dependencies and key store are ready.
Account, token, rooms, threads, and E2EE · Avoid maintaining homeserver and gateway uptime yourself
Best for
Teams already using Element or another Matrix client for private project rooms
Self-hosters who want the agent runtime and chat transport under their control
Engineering and operations rooms that benefit from thread and per-user context isolation
Encrypted approvals, incident summaries, cron reports, and tool-using workflows
Features
- ✓Any Matrix homeserver, including Synapse, Conduit, Dendrite, and matrix.org
- ✓Direct messages, rooms, MSC3440 threads, reactions, approvals, and model selection
- ✓Images, multiple images, files, voice/audio, and video attachments
- ✓Optional or required end-to-end encryption through mautrix and libolm
- ✓Per-user session isolation in shared rooms by default
- ✓Stable room-scoped sessions for project rooms with
MATRIX_SESSION_SCOPE=room - ✓Explicit user, room, mention, free-response, and bridge-ghost controls
- ✓Matrix-specific tools with cross-room and destructive actions disabled by default
Setup path
- 1Create a dedicated Matrix bot account on your homeserver or matrix.org. Using a personal account works for a solo assistant, but a separate identity is easier to secure and recover.
- 2Get an access token from Element under Settings → Help & About → Advanced. Treat it like a password: never paste it into chat or commit it.
- 3Run
hermes gateway setup, choose Matrix, and enter the homeserver URL, access token (or user ID plus password), and allowed Matrix user IDs. - 4Set both
MATRIX_ALLOWED_USERSandMATRIX_ALLOWED_ROOMSfor a private deployment. Without them, any sender or joined room that reaches the bot may be able to trigger an agent turn. - 5Keep
MATRIX_REQUIRE_MENTION=truefor shared rooms. Add only deliberate exceptions toMATRIX_FREE_RESPONSE_ROOMS, and keep room-wide@roommentions disabled. - 6Start or restart the gateway, invite the bot account to one private room, and send a harmless DM or
@mention. Count setup as complete only after the reply lands in Matrix. - 7For stable project-room context, use
MATRIX_SESSION_SCOPE=room; decide separately whethergroup_sessions_per_usershould isolate each participant or share one transcript. - 8Add E2EE only after ordinary messaging works. Install the Matrix encryption dependencies and libolm, set
MATRIX_E2EE_MODE=required, and back up the Matrix crypto store.
How the Hermes Matrix gateway behaves
Hermes connects to the homeserver through the mautrix Python SDK. DMs get their own sessions and respond without an @mention. Shared rooms require a mention by default, automatically accept room invitations, and can auto-create a thread for each answered message so concurrent work does not collapse into one timeline.
- •DMs: every allowed message can trigger Hermes;
MATRIX_DM_AUTO_THREADis off by default. - •Rooms:
MATRIX_REQUIRE_MENTION=trueis the safe default. - •Threads: replies stay in the Matrix thread and use an isolated session namespace.
- •Progress: Matrix can update threaded thinking/tool panes instead of flooding the room.
Room, thread, and per-user session isolation
Matrix has two independent context decisions. MATRIX_SESSION_SCOPE selects the room or thread lane, while group_sessions_per_user decides whether people inside a shared room get separate histories. The default per-user behavior protects token budgets and prevents one person's tool-heavy task from bloating or interrupting another person's context.
- •Use
MATRIX_SESSION_SCOPE=roomandMATRIX_AUTO_THREAD=falsefor one stable project-room lane. - •Keep
group_sessions_per_user: truewhen participants should not share context. - •Set it to false only for a deliberately collaborative room where shared history is useful.
- •Cross-room
/resumeis blocked unless explicitly requested, reducing accidental project-context leakage.
Private deployment hardening
A federated room is still untrusted input to a tool-using agent. Restrict users and rooms, ignore appservice bridge ghosts, leave m.notice processing and whole-room mentions off, and keep destructive or cross-room Matrix tools disabled unless the workflow truly needs them.
- •Set
MATRIX_ALLOWED_USERSandMATRIX_ALLOWED_ROOMS, not only one of them. - •Use
MATRIX_IGNORE_USER_PATTERNSfor Telegram, Slack, or WhatsApp bridge ghosts to avoid loops. - •Keep redaction, invites, public room creation, and cross-room tools disabled by default.
- •Use a dedicated Hermes profile when Matrix should have narrower memory, secrets, or terminal access.
End-to-end encryption without silent downgrade
Matrix E2EE is deployment-controlled. off skips crypto, optional attempts encryption but may keep unencrypted rooms working if crypto cannot initialize, and required fails closed. For a room advertised as encrypted, use required mode after installing mautrix encryption support and libolm; optional mode is not equivalent to guaranteed E2EE.
- •Crypto keys live under
~/.hermes/platforms/matrix/store/on current installs. - •Back up the store securely; losing it can prevent decryption of prior encrypted traffic.
- •Do the first gateway smoke test in an unencrypted private room, then enable required E2EE as a separate verified step.
- •Never commit recovery keys, access tokens, device IDs, or the crypto store.
Matrix versus Signal, Discord, and FlyHermes
Choose Matrix when rooms, federation, Element clients, self-hosted chat, and E2EE are requirements. Choose Signal for a lighter private phone workflow without operating a homeserver, or Discord for familiar team/community channels. Choose FlyHermes when the business goal is managed browser/mobile/channel access rather than owning homeserver, gateway, provider, backups, and incident recovery.
- •Matrix: strongest fit for self-hosted or federated team rooms.
- •Signal: simpler private mobile transport with a linked-device daemon.
- •Discord: familiar team channels and threads without Matrix homeserver operations.
- •FlyHermes: managed uptime when operating the messaging stack is not the product.
Common setup issues
- The bot does not connect — verify
MATRIX_HOMESERVER, token validity, and the active Hermes profile; then inspect current gateway logs rather than rotating credentials blindly. - DM works but a room is silent — confirm the room is in
MATRIX_ALLOWED_ROOMS, the sender is allowed, and the message includes an@mentionunless that exact room is free-response. - The bot answers old events after restart — update Hermes and mautrix; current handling ignores stale startup events, duplicate IDs, edits, notices, and the bot's own events.
- Users see the wrong context — inspect
MATRIX_SESSION_SCOPE, real thread roots, andgroup_sessions_per_user; room scope and per-user isolation are separate controls. - Encrypted messages fail — verify mautrix encryption support, libolm, the device/store path, and whether
MATRIX_E2EE_MODEis optional or required. - A bridge creates loops — add the bridge's ghost-user naming pattern to
MATRIX_IGNORE_USER_PATTERNSand leave notices disabled unless trusted humans need them. - Cron runs but no Matrix report arrives — verify the Matrix home room or explicit delivery target, gateway uptime, provider health, room membership, and one manual message to the same room.
- Media fails — Matrix downloads must use
mxc://content and remain underMATRIX_MAX_MEDIA_BYTES; inspect the attachment type and limit before widening access.
Keep building the workflow
Hermes gateway troubleshooting
Debug a connected homeserver or gateway that still does not receive or deliver real messages.
Hermes profiles guide
Isolate Matrix credentials, memory, skills, and tool permissions from other agents.
Hermes Web UI
Inspect the active profile, provider, sessions, logs, cron jobs, and gateway state.
Hermes cron jobs
Schedule work and verify the report reaches the intended Matrix room.
Signal setup
Compare Matrix rooms and federation with a lighter private messaging gateway.
FAQ
How do I connect Hermes Agent to Matrix?
Create a Matrix account for the bot, copy an access token, run hermes gateway setup, configure user and room allowlists, restart the gateway, invite the bot, and verify one real DM or room reply.
Does Hermes Agent support Matrix threads?
Yes. Real MSC3440 threads keep their own context, and Hermes can auto-create response threads in rooms. Use room scope when a project room needs one stable unthreaded lane.
Does Hermes Agent support encrypted Matrix rooms?
Yes, with mautrix encryption support and libolm installed. Use MATRIX_E2EE_MODE=required to fail closed instead of silently continuing without E2EE.
Why does Hermes require a mention in Matrix rooms?
Mention gating is the safe default in shared rooms. Disable it globally only with care, or add exact room IDs to MATRIX_FREE_RESPONSE_ROOMS.
Do people in one Matrix room share the same Hermes memory?
Not by default. group_sessions_per_user: true gives each participant a separate session inside the room. Set it to false only when one shared collaborative transcript is intentional.
Which Matrix environment variables are required?
Use MATRIX_HOMESERVER plus MATRIX_ACCESS_TOKEN; password login instead uses MATRIX_USER_ID and MATRIX_PASSWORD. A private deployment should also set MATRIX_ALLOWED_USERS and MATRIX_ALLOWED_ROOMS.
Can Matrix deliver Hermes cron reports?
Yes. Configure a Matrix home room or explicit delivery target, keep the gateway running, and verify the actual message in that room after the job runs.
Should I self-host Matrix access or use FlyHermes?
Self-host when federation, E2EE, homeserver control, and room-level customization justify the operational work. Choose FlyHermes when managed browser/mobile/channel uptime matters more than running that stack yourself.