Hermes Agent
Hermes Agent Matrix setup: bot, token, encryption and fixes
Updated 22 November 2026
Matrix is an open, federated chat protocol, and Hermes Agent can run as a Matrix bot on any spec-compliant homeserver. This page walks the whole job in order: a bot account, a way to log in, who and which rooms may talk to it, how threads and sessions behave, optional end-to-end encryption, and what to check when the bot stays silent.
Facts come from the Hermes Agent 0.23.3 Matrix page, the Messaging Gateway and Security pages and the environment variable reference, all read on 22 November 2026 (documentation for release 0.23.3, published 20 November 2026).
What the Matrix bot does
The docs say the bot connects with the mautrix Python SDK, runs messages through the normal Hermes pipeline (tools, memory, reasoning) and replies in real time. It handles text, files, images, audio and video, and can use end-to-end encryption (E2EE). The page names Synapse, Conduit, Dendrite and matrix.org as working homeservers. The behaviour you will notice first:
- Direct messages. Hermes answers every message with no mention needed, and each DM has its own session. Any room with two or fewer joined members counts as a DM, even if it has a name, because Matrix clients auto-name 1:1 chats.
- Rooms. By default Hermes only answers when it is
@mentioned. Room invites are accepted automatically, so inviting the bot’s Matrix user is enough to bring it in. - Threads. Hermes supports Matrix threads (MSC3440) and keeps a thread’s context apart from the main timeline. In threads where it has already taken part, no mention is needed.
- Reactions. Dangerous-command approval and
/modelselection can use reactions, and the bot posts short processing reactions on inbound messages. - Shared rooms. By default each person in a room gets a separate session, so two people do not share one transcript.
One trap: a deliberately created two-person room is still treated as a DM, so it bypasses MATRIX_ALLOWED_ROOMS, MATRIX_REQUIRE_MENTION and MATRIX_FREE_RESPONSE_ROOMS. The docs say to add a third member if you need it to behave like a regular room.
Step 1: create the bot account and find IDs
Hermes needs a Matrix account to post from. You can create an account for the bot or use your existing account, in which case its messages appear under your name. The docs give three routes:
- Your own homeserver (recommended). On Synapse, the docs show
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008. Pick a username such ashermes; the full ID becomes@hermes:your-server.org. - A public homeserver. Create a new account in Element Web at app.element.io, with a username like
hermes-bot. - Your own account. Hermes can run as you, in which case the bot posts as you. The docs suggest this for personal assistants.
Next, find the user ID of the person who will talk to the bot. In Element, click your avatar, open Settings, and the ID is shown at the top of the profile, for example @alice:matrix.org. Matrix user IDs start with @ and contain a colon before the server name. You will use this in the allowlist below.
For room restrictions you need a room’s internal ID, which starts with !. In Element it is under the room’s Settings, then Advanced. Use that, not the alias that starts with #.
Step 2: access token or password login
Hermes can authenticate in two ways. The docs recommend the access token.
Access token. Log in to Element as the bot account, open Settings, then Help & About, expand Advanced, and copy the token shown there. Or ask the homeserver directly:
curl -X POST https://your-server/_matrix/client/v3/login \
-H "Content-Type: application/json" \
-d '{
"type": "m.login.password",
"user": "@hermes:your-server.org",
"password": "your-password"
}'The response contains an access_token field. The docs warn that the token gives full access to the bot’s account: never share it or commit it to Git, and if it leaks, revoke it by logging out all sessions for that user.
Password login. Instead of a token, give Hermes the user ID and password and it logs in at startup. The docs call this simpler, with the cost that the password sits in your .env file:
MATRIX_USER_ID=@hermes:your-server.org
MATRIX_PASSWORD=your-passwordStep 3: configure, restrict access and start
The guided route is the setup command, run in your terminal:
hermes gateway setupChoose Matrix and enter the homeserver URL, the token (or user ID and password) and the allowed user IDs when asked. To do it by hand, add the values to ~/.hermes/.env. With a token:
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***
MATRIX_ALLOWED_USERS=@alice:matrix.example.org
MATRIX_ALLOWED_ROOMS=!abc123:matrix.example.orgReplace *** with the bot account’s access token and https://matrix.example.org with your homeserver URL. Put the full IDs of people you trust in MATRIX_ALLOWED_USERS and the internal IDs of group rooms in MATRIX_ALLOWED_ROOMS; separate several entries in either list with commas. MATRIX_USER_ID is optional with a token, because it is detected from the token. With password login, MATRIX_HOMESERVER, MATRIX_USER_ID and MATRIX_PASSWORD are the required three. Each user is in the full @user:server form. Include the https:// in the homeserver URL and no trailing slash.
Lock it down
The Matrix page says that if MATRIX_ALLOWED_USERS is unset, any sender who can reach the bot in a joined room can trigger an agent turn, and if MATRIX_ALLOWED_ROOMS is unset, any room the bot joins can. The gateway itself denies unauthorized users by default. For a private bot, set both Matrix lists, leave MATRIX_ALLOW_ALL_USERS and GATEWAY_ALLOW_ALL_USERS off, and check who already has access through pairing or GATEWAY_ALLOWED_USERS. The docs also warn that authorized users get the agent’s full capabilities, including tool use and system access, so only authorize people and rooms you trust. Federated rooms and untrusted homeservers should be treated as untrusted input; for tool-heavy work the docs prefer DMs or private rooms.
MATRIX_ALLOW_ALL_USERS exists, and the reference describes it as dev only. If you use a bridge, keep its ghost users out of the allowlist; the bridge section below covers loop protection.
Start the gateway
hermes gatewayThe docs say the bot should connect and start syncing within seconds. Send it a DM, or invite it to a room and mention it, to test. For a background service on Linux with systemd or macOS with launchd, use hermes gateway install, then hermes gateway start. The CLI reference recommends hermes gateway run for foreground use on WSL, Docker and Termux. On WSL, the documented way to keep it running after you close the terminal is tmux new -s hermes 'hermes gateway run'. Our gateway restart guide covers restarting it, and the Docker guide covers containers.
Rooms, threads, sessions and commands
The table lists environment variables you can set in ~/.hermes/.env.
| Setting | What it does |
|---|---|
MATRIX_REQUIRE_MENTION | Default true. Set false to answer every room message. |
MATRIX_FREE_RESPONSE_ROOMS | Comma-separated room IDs where no mention is needed. |
MATRIX_AUTO_THREAD | Default true: Hermes starts a thread for each message it answers in a room. |
MATRIX_DM_AUTO_THREAD | Default false. Set true to start a thread for each DM the bot answers. |
MATRIX_DM_MENTION_THREADS | Default false. Set true to start a thread when someone mentions the bot in a DM. |
MATRIX_SESSION_SCOPE | The default is auto, which keeps the existing MATRIX_AUTO_THREAD behaviour. The project-room example below explains room and thread. |
MATRIX_REACTIONS | Default true. Set false to stop the processing reactions in noisy rooms. |
MATRIX_ALLOW_ROOM_MENTIONS | Default false. Leave it off unless the bot may notify the whole room with @room. |
If you upgraded from a version that predates MATRIX_REQUIRE_MENTION, the docs note the bot used to answer every room message, and MATRIX_REQUIRE_MENTION=false restores that.
Project rooms
If one bot sits in several project rooms, the docs recommend stable room-scoped sessions:
MATRIX_SESSION_SCOPE=room
MATRIX_AUTO_THREAD=falseWith room, unthreaded messages share one room session while real Matrix threads still use their own root. With thread, an unthreaded message starts a session from its own event ID. Whether people in the room share a transcript is a separate switch, group_sessions_per_user in ~/.hermes/config.yaml, true by default. Setting it to false gives the room one shared conversation, which the docs say also shares context growth and token costs and lets one person’s run interrupt another’s. /resume will not pick up a named session from another room unless you use /resume --cross-room with the session name.
Commands and the home room
Normal slash commands work. If your Matrix client keeps / for its own commands, type !commands, !model, !stop and so on; Hermes only converts a ! word that is a known command, plugin command or installed skill, so !important stays a normal message.
A home room receives proactive output such as scheduled-job results. Type /sethome (or !sethome) in the room, or set MATRIX_HOME_ROOM in ~/.hermes/.env. The environment reference also lists MATRIX_HOME_CHANNEL for default delivery; the Matrix page itself uses MATRIX_HOME_ROOM.
Bridges and notices
Hermes ignores its own events, appservice-style users whose localpart starts with an underscore, duplicate events, old startup events, edits and m.notice events by default. If a bridge uses other ghost names, add patterns:
MATRIX_IGNORE_USER_PATTERNS='^@telegram_,^@slack_,^@whatsapp_'Only set MATRIX_PROCESS_NOTICES=true for a trusted workflow. Notices grant no access: the sender still needs to be allowed, and the bot-loop guard applies: after Hermes replies to a notice, it ignores that sender’s next notice until someone sends a regular message in the room or the room goes 10 minutes without a notice. A trusted workflow that needs back-and-forth can set gateway.bot_loop_guard.bot_replies_expect_reply: true in config.yaml; the default limit is four hops.
End-to-end encryption
E2EE needs the mautrix encryption extras and the libolm C library. The Matrix page gives this command for the declared Matrix dependencies, from a source checkout prepared with the project’s package manager, and these system packages:
python -c "import pm; pm.sync_venv(['matrix'], explicit=True)"sudo apt install libolm-dev
brew install libolm
sudo dnf install libolm-develThose are the Debian or Ubuntu, macOS and Fedora lines in that order, but the matrix extra is Linux-only: on macOS or Windows, use the container route in “E2EE on a Mac or Windows host” below. On Linux, switch it on in ~/.hermes/.env:
MATRIX_E2EE_MODE=requiredThe modes are off (no E2EE), optional (try it, and keep unencrypted rooms working if crypto cannot start) and required (fail closed if the dependencies or setup are missing). The older MATRIX_ENCRYPTION=true still enables required behaviour, and MATRIX_E2EE_MODE overrides it when set. If crypto cannot start, optional mode may continue serving unencrypted rooms. In required mode, Hermes refuses to continue without working encryption, so choose required if you need encryption. Reactivate the checkout after changing dependencies, and set the device ID and any recovery key described below before restarting Hermes.
With E2EE on, Hermes keeps its keys in ~/.hermes/platforms/matrix/store/ (older installs use ~/.hermes/matrix/store/), uploads device keys on first connection, joins encrypted rooms on invite and handles decryption and encryption itself. Set a stable device ID so the keys survive restarts; the reference says that without MATRIX_DEVICE_ID the E2EE keys rotate on every startup and decrypting history in old rooms breaks:
MATRIX_DEVICE_ID=HERMES_BOTCross-signing
If the account has cross-signing (the default in Element), set the recovery key so the bot can sign its own device at startup; otherwise other clients may refuse to share encryption sessions after a device key rotation. In Element it is under Settings, Security & Privacy, Encryption, also called the Security Key.
In ~/.hermes/.env, set MATRIX_RECOVERY_KEY to the recovery key you saved when you set up cross-signing for that account.
On each start, Hermes imports the cross-signing keys from the homeserver’s secret storage and signs the device; the docs call this safe to leave on permanently. If Hermes has to create a new recovery key it never logs it. Set MATRIX_RECOVERY_KEY_OUTPUT_FILE to a path before startup to have it written once with mode 0600, and never overwritten.
E2EE on a Mac or Windows host
The matrix extra is limited to Linux. On macOS or Windows the docs describe proxy mode: a Linux container runs only the Matrix adapter and encryption, and forwards each decrypted message to the native Hermes on the host. On the host, set API_SERVER_ENABLED=true and choose a strong random secret for API_SERVER_KEY. The example sets API_SERVER_HOST=0.0.0.0 so the container can reach the server; this listens on every host network interface, on port 8642 by default. For the container, use the repository’s Docker build on a compatible Linux target, which includes the Matrix dependencies. Configure the bot’s Matrix credentials, access restrictions, encryption setting and stable device ID in the container. Set GATEWAY_PROXY_URL to the host API server’s URL and GATEWAY_PROXY_KEY to the host’s API_SERVER_KEY, and mount a persistent volume at /root/.hermes/platforms/matrix/store. Start the host gateway first, check from the Linux VM that the host’s /health endpoint is reachable, then, from the directory holding the docker-compose.yml example from the Matrix page’s container step (filled in with your Matrix settings and proxy key), run docker compose up -d and send a message in an encrypted room. The documented limits: tool progress messages are not relayed and dangerous-command approvals are handled on the host, not in Matrix. See the API server page for the host side.
Troubleshooting
- Not responding. The cause the docs list: the bot has not joined, your ID is not in
MATRIX_ALLOWED_USERS, the room is not inMATRIX_ALLOWED_ROOMS, or a room message did not mention the bot. Invite it, check the full@user:serverform and the room ID, mention it or add the room toMATRIX_FREE_RESPONSE_ROOMS, then restart the gateway. - Joins rooms but drops every message. Check for clock skew if the log says “Matrix: dropped N live events as ‘too old’ more than 30s after startup”. The adapter filters out events timestamped more than five seconds before startup, so a host clock that is ahead can make live messages look old enough to drop. Sync the clock with
sudo timedatectl set-ntp trueon Debian or Ubuntu (check withtimedatectl status) orsudo sntp -sS time.apple.comon macOS, then restart. - “Failed to authenticate” or “whoami failed”. The token or the homeserver URL is wrong. First check that
MATRIX_HOMESERVERbegins withhttps://and has no trailing slash, then replacehttps://your-serverandYOUR_TOKENin this test:curl -H "Authorization: Bearer YOUR_TOKEN" https://your-server/_matrix/client/v3/account/whoami. If it returns your user info the token is valid; if not, generate a new one. - “mautrix not installed”. Run the Python dependency command in the encryption section from your prepared checkout; the docs also show running it from
~/.hermes/hermes-agent. After the dependencies change, reactivate the checkout and restart Hermes. - Cannot decrypt, or “could not decrypt event”. Check that
libolmis installed, that encryption is switched on in.env, and that you trust the bot’s device in Element (the bot’s profile, then Sessions). A bot that has just joined an encrypted room can only read messages sent after it joined. - Connects and sends, but ignores inbound messages. Hermes runs its own sync loop that passes every sync response to mautrix’s handler. If incoming messages still fail after a gateway restart, check the logs for “sync event dispatch error” and verify that the adapter registered its message handlers before the first sync.
- Falls behind. Long tool runs or a slow homeserver can delay syncing. The loop retries every 5 seconds on error; check the Hermes logs for sync warnings and the homeserver’s resources.
- Bot offline. Make sure the gateway is running and read its terminal output. The docs’ usual suspects are a wrong homeserver URL, an expired token and an unreachable homeserver.
- “User not allowed” or ignored room. For “User not allowed”, add the person’s full Matrix user ID to
MATRIX_ALLOWED_USERS. If a trusted group room is being ignored, add its internal room ID toMATRIX_ALLOWED_ROOMSand mention the bot. Restart the gateway after changing the lists. - Bridge messages loop or echo. Keep ghost users out of the allowed list, add a matching
MATRIX_IGNORE_USER_PATTERNSentry and leaveMATRIX_PROCESS_NOTICESfalse.
After upgrading an old encrypted setup
If you used MATRIX_ENCRYPTION=true with an older Hermes and moved to the SQLite-based crypto store, the bot’s encryption identity changed, and Element may cache the old device keys. The symptom is the log saying E2EE is enabled while every message shows as undecryptable. The documented one-time fix:
This one-time migration discards the old encryption keys. Afterward, the bot cannot decrypt messages sent before the upgrade. New installations can skip these steps.
- Before sending the login request from Step 2 (with the bot’s password), replace its top-level
userfield with"identifier": {"type": "m.id.user", "user": "@hermes:your-server.org"}using the bot’s full ID, and add"initial_device_display_name": "Hermes Agent". Send it once and copy the returnedaccess_tokenintoMATRIX_ACCESS_TOKENin~/.hermes/.env. - Delete the old state:
rm -f ~/.hermes/platforms/matrix/store/crypto.dbandrm -f ~/.hermes/platforms/matrix/store/crypto_store.*. - Set
MATRIX_RECOVERY_KEYif you use cross-signing. - In Element, open the DM with the bot and type
/discardsessionto force a new encryption session. - Restart with
hermes gateway run. With a recovery key set, the log should say cross-signing was verified via the recovery key. Then send a new message.
If you deleted the crypto store
Deleting ~/.hermes/platforms/matrix/store/crypto.db costs the bot its encryption identity, and restarting with the same device ID does not fully recover it, because the homeserver still holds one-time keys signed with the old identity. Hermes detects this at startup and refuses to enable E2EE, logging that the device has stale one-time keys. The docs call a new access token the easiest recovery. To keep the same device ID, follow the manual recovery procedure on the official page. For direct database recovery, stop Synapse, remove only the specified records matching both the bot’s user ID and device ID, then start Synapse again. Alternatively, use the running server’s admin API to delete the device, which may invalidate its access token. After either route, remove the local ~/.hermes/platforms/matrix/store/crypto.db* files, restart Hermes and type /discardsession in Element. Read the full steps on the official page before touching a homeserver database.
Matrix on ReadyHermes
Matrix is not offered in the ReadyHermes Channels panel. We have not tested connecting it on a ReadyHermes assistant and do not support it, so this page is for people running Hermes themselves. The Channels panel offers Telegram, WhatsApp, Discord, WeChat, Lark and the Hermes Desktop connection. See Hermes Agent Telegram, WhatsApp and Discord if one of those fits.
Self-hosting Matrix means running the gateway, keeping the clock correct and looking after the encryption store yourself, which is a fair price if you already run a homeserver. If you would rather have an always-on agent without that upkeep, ReadyHermes plans start at 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. See self-hosting vs managed hosting to compare.
Questions
How do I connect Hermes Agent to Matrix?
Create a Matrix account for the bot, then run hermes gateway setup and choose Matrix. For manual setup, set MATRIX_HOMESERVER and MATRIX_ALLOWED_USERS in ~/.hermes/.env, then add MATRIX_ACCESS_TOKEN for token login or MATRIX_USER_ID and MATRIX_PASSWORD for password login. For a shared or private deployment, also set MATRIX_ALLOWED_ROOMS to the trusted room IDs before starting the gateway. Start it with hermes gateway and test with a DM from an authorized user.
Access token or password login: which should I use?
The Hermes docs recommend the access token. Password login works with MATRIX_USER_ID and MATRIX_PASSWORD and is simpler, but the password is stored in your .env file.
Why does the Matrix bot not answer in a room?
The docs list four causes: the bot has not joined the room, your ID is not in MATRIX_ALLOWED_USERS, the room is not in MATRIX_ALLOWED_ROOMS, or the message did not mention the bot. A clock set ahead of real time can also make the bot drop every message. Fix the cause and restart the gateway.
Does Hermes Agent support end-to-end encrypted Matrix rooms?
Yes. Install the mautrix encryption extras and libolm. Set MATRIX_E2EE_MODE to required if the bot must have working encryption, or optional to allow unencrypted rooms to keep working if encryption cannot start. The older MATRIX_ENCRYPTION=true setting also enables required behaviour when MATRIX_E2EE_MODE is unset. It stores keys in ~/.hermes/platforms/matrix/store/, and setting MATRIX_DEVICE_ID keeps them stable across restarts. On macOS or Windows the docs describe a Linux container in proxy mode.
Can I use Matrix on ReadyHermes?
Matrix is unavailable in the ReadyHermes Channels panel. We have not tested connecting it to a ReadyHermes assistant and do not support that setup. The panel offers Telegram, WhatsApp, Discord, WeChat, Lark and the Hermes Desktop connection.