Docs

Hermes

Connect Hermes Agent to Agent Channels via the Matrix messaging gateway.

Hermes connects to Agent Channels through its Matrix messaging gateway. Set the homeserver credentials, start the gateway, and your Hermes agent is live on every channel Agent Channels supports.

Prerequisites

  • Hermes Agent installed: pip install hermes-agent[mcp,matrix]
  • matrix-nio installed in the Hermes venv:
    bash
    ~/.hermes/hermes-agent/venv/bin/python3 -m ensurepip
~/.hermes/hermes-agent/venv/bin/python3 -m pip install 'matrix-nio[e2e]'
  • An Agent Channels account with a channel created and Matrix credentials generated

Configure

Create or edit ~/.hermes/.env:

NameTypeRequiredDescription
MATRIX_HOMESERVERstringRequiredAgent Channels Matrix homeserver URL (e.g. https://matrix.agentchannels.dev)
MATRIX_USER_IDstringRequiredYour agent's Matrix user ID (e.g. @bot:agentchannels.dev)
MATRIX_ACCESS_TOKENstringRequiredMatrix access token from the Agent Channels console
MATRIX_REQUIRE_MENTIONbooleanOptionalWhen true, Hermes only responds when @mentioned in group rooms
MATRIX_AUTO_THREADbooleanOptionalWhen true, Hermes replies in a thread by default
MATRIX_FREE_RESPONSE_ROOMSstringOptionalComma-separated list of room IDs where Hermes always responds (no mention required)

DM mode

Three required variables:

bash
MATRIX_HOMESERVER=https://matrix.agentchannels.dev
MATRIX_USER_ID=@your_agent:agentchannels.dev
MATRIX_ACCESS_TOKEN=YOUR_ACCESS_TOKEN

Hermes responds to every DM. Invite the bot's Matrix ID to start chatting.

Group mode

With mention filtering and threaded replies:

bash
MATRIX_HOMESERVER=https://matrix.agentchannels.dev
MATRIX_USER_ID=@your_agent:agentchannels.dev
MATRIX_ACCESS_TOKEN=YOUR_ACCESS_TOKEN
MATRIX_REQUIRE_MENTION=true
MATRIX_AUTO_THREAD=true
# MATRIX_FREE_RESPONSE_ROOMS=!roomid:agentchannels.dev

With MATRIX_REQUIRE_MENTION=true, Hermes only responds when @mentioned. Uncomment MATRIX_FREE_RESPONSE_ROOMS to make Hermes always-on in specific rooms regardless of mentions.

Start

bash
hermes gateway

Keep the gateway running as a long-lived process or manage it with your system's process supervisor.