# How to set up Hermes Agent on Matrix

> Create a Matrix bot account, configure its credentials and allowlists, choose an encryption mode and start a private conversation.

Canonical: https://hermeswatcher.com/learn/hermes-agent-matrix-setup  
Section: Learn · Messaging & the gateway  
Last reviewed: Oct 29, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## 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](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/matrix#proxy-mode-e2ee-on-macos): 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](https://app.element.io) and choose Create Account. Select the intended homeserver, register a separate bot identity and complete that server's registration and email checks. [Element onboarding](https://docs.element.io/latest/element-support/quick-start-guide/onboarding/) describes this flow.

Sign into Element as the bot. Open Settings → Help & About. Under Advanced, reveal Access Token and copy it. The [Element FAQ](https://docs.element.io/latest/element-support/frequently-asked-questions/) 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](https://hermes-agent.nousresearch.com/docs/reference/package-management#developer-workflow), 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](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md).

## 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](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) 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](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/matrix)

## Related guides

- [All messaging platforms](https://hermeswatcher.com/messaging.md)
- [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md)
- [How to set up Hermes Agent on Slack](https://hermeswatcher.com/learn/hermes-agent-slack-setup.md)
- [How to set up Hermes Agent on Google Chat](https://hermeswatcher.com/learn/hermes-agent-google-chat-setup.md)
- [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md)

## Related tools

- [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md)
- [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md)
- [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md)

## Sources

- [Hermes Agent: Matrix](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/matrix)
- [Element: account onboarding](https://docs.element.io/latest/element-support/quick-start-guide/onboarding/)
- [Element: access token FAQ](https://docs.element.io/latest/element-support/frequently-asked-questions/)
- [Package management: source checkout workflow](https://hermes-agent.nousresearch.com/docs/reference/package-management#developer-workflow)
- [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)
- [Gateway authorization source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L660-L772)
- [Native Windows settings paths](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native)
- [pyproject.toml](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/pyproject.toml)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt