How to set up Hermes Agent on Matrix

What you need

Matrix is a messaging protocol that connects accounts through homeservers. A homeserver is the server that hosts your Matrix account. Hermes signs into a Matrix account and receives messages through that server.

Platform support: the Matrix dependencies are Linux-only, including WSL2. Native macOS and Windows cannot load the adapter directly. Use a Linux host or WSL2, or official Proxy Mode↗ (opens in a new tab): a Linux container runs the adapter and forwards requests to your host's API server. Proxy Mode exposes the host's API server to the container, so it needs a strong API_SERVER_KEY and network protection. In v1, approval prompts are handled on the host rather than in Matrix, and tool progress is not relayed.

• Hermes Agent installed with a model provider configured.
• A dedicated Matrix account for the bot on a homeserver where you can register or have an administrator create it. You can use a public or self-hosted server.
• The bot's homeserver URL and access token, or its full user ID and password for the documented password-login alternative.
• Your own full Matrix user ID, such as @alice:matrix.example.org, for access control.
• The Matrix Python dependencies (the matrix extra, Linux only) are needed to connect. Hermes can request them on first use. Encrypted rooms also need the system libolm library.
• A computer with access to the homeserver that stays on whenever you want the bot available.

Create the bot account and get its token

For the client-based route, open Element Web↗ (opens in a new tab) and choose Create Account. Select the intended homeserver, register a separate bot identity and complete that server's registration and email checks. Element onboarding↗ (opens in a new tab) describes this flow.

Sign into Element as the bot. Open Settings → Help & About. Under Advanced, reveal Access Token and copy it. The Element FAQ↗ (opens in a new tab) confirms this token grants full account access.

Record the full bot user ID and homeserver URL. In your own account, open profile settings and copy your full Matrix user ID for the sender allowlist. A display name is not a user ID.

Keep the token secret and out of Git, screenshots and shared messages. The Hermes docs say to revoke compromised account sessions. An administrator can also create the bot account on a private server; this guide uses Element rather than installing a new homeserver.

Password login is another documented option. It stores the bot's password in the profile configuration, so it needs the same private handling as a token.

Choose who can talk to it

An allowlist is the list of people permitted to use the agent. Authorize only people you trust with its enabled tools and files. Keep GATEWAY_ALLOW_ALL_USERS unset or false and review existing global allowlists and pairing approvals, which can also grant access. Do not expect an unknown sender to receive a pairing code when an allowlist is set.

Set MATRIX_ALLOWED_USERS to the full IDs of trusted people. For shared rooms, also set MATRIX_ALLOWED_ROOMS to their internal room IDs, such as !abc123:matrix.example.org. In Element, the Hermes docs point to room settings → Advanced for the internal ID. A #room:server alias is not the internal ID.

The room allowlist does not restrict DMs. The official page says rooms with two or fewer joined members are treated as DMs, even when named. Those conversations bypass room filtering and mention rules, so the user allowlist remains essential.

The bot automatically accepts room invitations. A room invitation or an @mention should not be treated as permission to operate the agent. Do not leave access implicit or use an empty allowlist as an access policy.

Connect it to Hermes

Run the setup wizard and select Matrix. Provide the homeserver URL, credentials and allowed user IDs. To configure manually, use one of these credential alternatives in the active profile .env.

These adapter settings belong to the Linux or WSL2 installation, normally in ~/.hermes/.env. For a native macOS or Windows agent, use the separate Proxy Mode instructions. If you use a custom Hermes home or another profile, edit that profile's file instead. Replace every example value before starting.

Setup wizard

hermes gateway setup

Profile .env, token alternative

MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***
MATRIX_ALLOWED_USERS=@alice:matrix.example.org
MATRIX_ALLOWED_ROOMS=!abc123:matrix.example.org

Profile .env, password alternative

MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@hermes:matrix.example.org
MATRIX_PASSWORD=***
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

Use either your real token or the password-login settings; *** is only a secret placeholder. The password example still needs MATRIX_ALLOWED_ROOMS if you will use shared rooms. Separate multiple users or rooms with commas.

Keep user separation enabled for shared rooms. The official page describes group_sessions_per_user: true as the default, giving participants separate context within a room. Turning it off shares a transcript and its context costs.

Prepare dependencies and choose encryption deliberately

End-to-end encryption (E2EE) encrypts messages between Matrix clients. The official Hermes page supports off, optional and required modes. Choose the mode before starting an encrypted conversation.

The official page gives this command for the Matrix extra. Run it only in a PM-prepared Hermes source checkout↗ (opens in a new tab), then reactivate the checkout and restart Hermes. PM is the Hermes package manager.

Activated Hermes source checkout

python -c "import pm; pm.sync_venv(['matrix'], explicit=True)"

Debian or Ubuntu, for encryption

sudo apt install libolm-dev

Fedora, for encryption

sudo dnf install libolm-devel

Profile .env, refuse to run if encryption can't start

MATRIX_E2EE_MODE=required

On the Linux host or WSL2 installation, use the system-library command for your distribution. For a native macOS or Windows agent, follow Proxy Mode instead of installing the adapter natively.

off does not initialize end-to-end encryption. optional tries encryption but keeps unencrypted rooms usable if crypto cannot initialize. required fails closed if dependencies or crypto setup are missing. Use required when encrypted operation is a requirement.

Required mode is not proof that every room is encrypted. Choose an encrypted Matrix conversation and check its state in your client. The bot can decrypt content to process it; Matrix transport encryption does not describe what an external model provider receives.

Keep ~/.hermes/platforms/matrix/store/ private and persistent. The official docs warn that deleting its crypto database destroys the bot's encryption identity and can require recovery. Do not delete it as a routine troubleshooting step.

For cross-signing, the official page documents MATRIX_RECOVERY_KEY so the bot can sign its device. Use only the bot account's recovery key and protect it like a password. If an encrypted conversation fails, follow the official device-verification instructions before sending sensitive material.

Start the gateway and send your first message

Start the foreground gateway and read its connection and encryption logs. From your allowed personal account, invite the bot's full Matrix ID to a private DM or an intended room.

Foreground gateway

hermes gateway

The docs describe automatic acceptance of invitations. In a DM, send Hello. In a regular room, @mention the bot. Confirm the response in your Matrix client before relying on the connection.

If you need encrypted chat, confirm that the conversation is encrypted and follow the official instructions to verify or trust the bot's device. A successful login or sync alone does not establish decryption.

For scheduled output, set the destination from the intended conversation with /sethome, or !sethome if your client intercepts slash commands. The documented environment setting is MATRIX_HOME_ROOM, containing the internal room ID.

What it can do

• The official comparison table lists voice, images, files, threads, reactions, typing indicators and streaming updates for Matrix. The platform page also documents video and optional encryption.
• DMs normally do not need a mention. Regular rooms need one by default; threads where the bot has participated can continue without another mention. The default room behavior creates threads to keep conversations separate.
• Use normal slash commands when your Matrix client sends them. If it intercepts them, Hermes documents known !command aliases, such as !sethome.
• Voice bubbles depend on a client that supports the documented Matrix voice-message extension. Incoming voice can be routed to speech-to-text; speech services still need their own configuration.
• Media is uploaded to the homeserver. The documented default media limit is 100 MB. Inbound media must use Matrix content URIs beginning mxc://, rather than arbitrary web download URLs.
• Approvals and model selection can use reactions. Approval controls are requester-bound by default when Hermes knows who requested the action.
• The adapter does not expose room creation, invitations or redaction as Matrix-specific agent tools. Do not confuse internal adapter controls with tools you can ask the model to use.

Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep.

After your first message succeeds, stop the foreground gateway with Ctrl+C. For a normal host installation, the official gateway docs give these service commands:

Install, start and inspect the host service

hermes gateway install
hermes gateway start
hermes gateway status

For this Linux or WSL2 adapter, use the Linux service instructions. macOS and native Windows need the separate Linux Proxy Mode adapter. On a headless Linux host using a user service, the docs give sudo loginctl enable-linger $USER to keep it available after logout. Windows Task Scheduler does not restart a gateway that crashes after its launcher exits.

In a container, use the documented container startup and restart policy instead of installing a host user service. For hosting choices, see How to run Hermes Agent 24/7 on a VPS or home server.

If it doesn't answer

• Bot appears offline: check that the gateway is running, the homeserver URL is reachable and the token is valid.
• Bot joins but ignores you: check your full @user:server ID in MATRIX_ALLOWED_USERS, then restart after changing configuration.
• A regular room is silent: check its internal ID against MATRIX_ALLOWED_ROOMS and @mention the bot. Remember that DM-classified rooms bypass that room filter.
• Missing Matrix dependency: request the Matrix extra through PM in the correct source environment, reactivate it and restart.
• Decryption errors: check libolm, the selected encryption mode and trust in the bot's device. The official page warns against assuming access to messages from before the bot joined. Follow its E2EE recovery section for an existing damaged identity.
• Connected and able to send, but no inbound replies: inspect sync-related errors in gateway logs. A successful outbound message alone does not establish that event handling is healthy.
• Bridge traffic echoes: keep bridge or appservice identities out of your sender allowlist. Leave notice processing at its default unless a trusted workflow needs it.
• See Hermes Agent bot not responding in your chat app for the general gateway checklist.
• Connected but all messages are ignored: check the host clock. A clock running ahead can make live events appear too old. Enable NTP time synchronization and restart.

Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

Official Hermes Matrix docs↗ (opens in a new tab)

Related guides

• All messaging platforms
• Hermes Agent messaging gateway explained
• How to set up Hermes Agent on Slack
• How to set up Hermes Agent on Google Chat
• Hermes Agent bot not responding in your chat app

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher