Hermes XMPP Plugin: messaging bridge for Hermes Agent

XMPP and Jabber gateway platform plugin for Hermes Agent, with group rooms and optional OMEMO

What Hermes XMPP Plugin does

The plugin registers an XMPP platform with the Hermes gateway through ctx.register_platform. It supports 1:1 chats and MUC group rooms, requires STARTTLS to the XMPP server, and implements typing indicators (XEP-0085), HTTP file upload (XEP-0363), data forms (XEP-0004), ad-hoc commands (XEP-0050), message markup (XEP-0394), threaded replies (XEP-0461), reactions (XEP-0444) and stateless file sharing for voice messages (XEP-0447). Cron and send_message delivery work through a standalone sender hook.

Configuration uses environment variables in ~/.hermes/.env or a config.yaml block, and env vars win when both are set. Access is limited to the bare JIDs in XMPP_ALLOWED_USERS, while rooms listed in XMPP_MUC_ROOMS are accepted by membership. OMEMO is optional and needs slixmpp-omemo. If a recipient has not published device keys, messages fall back to plaintext with a log warning. Each Hermes profile has its own .env, memory and gateway process, so each profile can have its own JID.

Key features

1:1 chats and MUC group rooms
Mandatory STARTTLS to the XMPP server
File and media upload through XEP-0363
Reactions, threaded replies, typing indicators and message markup
Optional OMEMO end-to-end encryption for 1:1 messages
Cron and send_message delivery over XMPP

When to use it

Chat with your Hermes agent from any XMPP client on a self-hosted server
Give each family member a separate Hermes profile with its own JID
Receive scheduled job output over XMPP

Who it is for: Self-hosters who run their own XMPP server, such as Prosody or ejabberd, and want Hermes Agent reachable over it.

How it fits with Hermes Agent

Built for Hermes Agent as a user plugin for the gateway, installed into the plugins folder of the Hermes profile you want to use.

How to install Hermes XMPP Plugin

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

cd ~/.hermes/plugins
git clone https://github.com/fastfinge/hermes-xmpp-plugin.git
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python -r ~/.hermes/plugins/hermes-xmpp-plugin/requirements.txt
hermes config set plugins.enabled '["hermes-xmpp-plugin"]'

Requirements: An XMPP account (JID and password), a server with MUC and HTTP file upload for those features, such as Prosody, and slixmpp-omemo for optional OMEMO

Note: It packages the work from upstream Hermes Agent XMPP pull requests as an optional user plugin because the core pull request had not yet landed.

FAQ

What is Hermes XMPP Plugin?

Hermes XMPP Plugin is a third-party platform plugin that connects the Hermes gateway to XMPP or Jabber. It supports direct chats, group rooms, file transfer and optional OMEMO encryption.

Does Hermes XMPP Plugin work with Hermes Agent?

Yes, it is built for Hermes Agent. It is installed into ~/.hermes/plugins and enabled with hermes config set plugins.enabled, then the gateway is restarted.

How do I install Hermes XMPP Plugin?

Clone the repository into ~/.hermes/plugins, install requirements.txt into the Hermes virtual environment with uv, and enable the plugin. After that, set XMPP_JID, XMPP_PASSWORD and XMPP_ALLOWED_USERS in ~/.hermes/.env and run hermes gateway restart.