Hermes Agent Matrix Setup: Rooms, Threads, and E2EE

hermes gateway setup

MATRIX_ALLOWED_USERS=@user1:example.com,@user2:example.com
MATRIX_ALLOWED_ROOMS=!room1:example.com,!room2:example.com

MATRIX_REQUIRE_MENTION=true
MATRIX_FREE_RESPONSE_ROOMS=!freeforall:example.com

hermes gateway start

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. According to the documentation:

• Use MATRIX_SESSION_SCOPE=room and MATRIX_AUTO_THREAD=false for one stable project-room lane.
• Keep group_sessions_per_user: true when participants should not share context.
• Set it to false only for a deliberately collaborative room where shared history is useful.
• Cross-room /resume is blocked unless explicitly requested, reducing accidental project-context leakage.

Configuration Example

In your Hermes profile YAML or environment:

matrix:
  session_scope: room
  auto_thread: false
  group_sessions_per_user: true

Or as environment variables:

MATRIX_SESSION_SCOPE=room
MATRIX_AUTO_THREAD=false
MATRIX_GROUP_SESSIONS_PER_USER=true

Private Deployment Hardening

A federated room is still untrusted input to a tool-using agent. The documentation provides several hardening recommendations:

Restrict Users and Rooms

Set both MATRIX_ALLOWED_USERS and MATRIX_ALLOWED_ROOMS, not only one of them. This ensures that even if a user is allowed, they can only interact with the bot in approved rooms.

Ignore Bridge Ghosts

Use MATRIX_IGNORE_USER_PATTERNS for Telegram, Slack, or WhatsApp bridge ghosts to avoid loops. Bridge ghosts are virtual users that represent users from other platforms. If the bot responds to a ghost, the ghost may forward the response back to the other platform, creating a loop.

MATRIX_IGNORE_USER_PATTERNS=@telegram_*,@slack_*,@whatsapp_*

Disable Destructive Tools

Keep redaction, invites, public room creation, and cross-room tools disabled by default. The documentation notes that Matrix-specific tools with cross-room and destructive actions are disabled by default. Only enable them if your workflow truly needs them.

Use a Dedicated Hermes Profile

Use a dedicated Hermes profile when Matrix should have narrower memory, secrets, or terminal access. This isolates the Matrix gateway from other agents or transports.

End-to-End Encryption Without Silent Downgrade

Matrix E2EE is deployment-controlled. The documentation defines three modes:

• off: Skips crypto entirely. Messages are sent unencrypted.
• optional: Attempts encryption but may keep unencrypted rooms working if crypto cannot initialize. This mode is not equivalent to guaranteed E2EE.
• required: Fails closed. If encryption cannot be established, the bot will not send or receive messages in that room.

For a room advertised as encrypted, use required mode after installing mautrix encryption support and libolm. The documentation warns that optional mode is not equivalent to guaranteed E2EE.

Crypto Store Location

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.

Security Practices

Never commit recovery keys, access tokens, device IDs, or the crypto store to version control. The documentation is explicit about this.

Matrix vs. Other Transports

The documentation provides a comparison to help you decide when to use Matrix:

• Matrix: Strongest fit for self-hosted or federated team rooms. Choose when rooms, federation, Element clients, self-hosted chat, and E2EE are requirements.
• Signal: Simpler private mobile transport with a linked-device daemon. Choose for a lighter private phone workflow without operating a homeserver.
• Discord: Familiar team channels and threads without Matrix homeserver operations. Choose for familiar team/community channels.
• FlyHermes: Managed browser/mobile/channel access. Choose when the business goal is managed uptime rather than owning homeserver, gateway, provider, backups, and incident recovery.

Troubleshooting

The documentation lists several common setup issues and their solutions:

Bot Does Not Connect

Verify MATRIX_HOMESERVER, token validity, and the active Hermes profile. Inspect current gateway logs rather than rotating credentials blindly. The documentation advises against rotating credentials without first checking logs.

DM Works but Room Is Silent

Confirm the room is in MATRIX_ALLOWED_ROOMS, the sender is allowed, and the message includes an @mention unless that exact room is free-response. If the room is not in the allowlist, the bot will ignore all messages.

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. If you are on an older version, the bot may replay old events after a restart.

Users See Wrong Context

Inspect MATRIX_SESSION_SCOPE, real thread roots, and group_sessions_per_user. Room scope and per-user isolation are separate controls. If users are seeing each other's context, check that group_sessions_per_user is set to true.

Encrypted Messages Fail

Verify mautrix encryption support, libolm, the device/store path, and whether MATRIX_E2EE_MODE is optional or required. If crypto cannot initialize, messages will fail silently in optional mode or fail loudly in required mode.

Bridge Creates Loops

Add the bridge's ghost-user naming pattern to MATRIX_IGNORE_USER_PATTERNS and leave notices disabled unless trusted humans need them. Bridge loops can cause infinite message exchanges.

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. If the gateway is down, cron reports will not be delivered.

Media Fails

Matrix downloads must use mxc:// content and remain under MATRIX_MAX_MEDIA_BYTES. Inspect the attachment type and limit before widening access. The default media size limit may be too small for large files.

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.

Going Further

Once your Matrix gateway is working, the documentation suggests several next steps:

• 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.

You can also explore other integrations like Telegram, Discord, Slack, and WhatsApp, each with their own setup guides on the Hermes Agent documentation site.