hacky.bot/hermes-xmpp-gateway
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
5 commits 1 branch 0 tags 52 KiB
  • Python 100%
Find a file
Exact
Hermes Agent f87b82e81f fix: rename plugin to 'xmpp', add env_enablement_fn + cron_deliver_env_var 
- plugin.yaml: name changed from 'xmpp-platform' to 'xmpp' so it
  matches the plugins.enabled entry in config.yaml (key is derived
  from manifest.name for flat user plugins)
- adapter.py: add _env_enablement_fn() to seed PlatformConfig.extra
  from env vars at config load time (v0.13.0 requirement)
- adapter.py: add cron_deliver_env_var="XMPP_HOME_CHANNEL" so the
  platform is a valid cron deliver= target

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-08 10:16:34 +07:00
__init__.py feat: migrate to pluggable platform plugin (Hermes v0.12.0) 2026-05-01 22:19:53 +07:00
adapter.py fix: rename plugin to 'xmpp', add env_enablement_fn + cron_deliver_env_var 2026-05-08 10:16:34 +07:00
plugin.yaml fix: rename plugin to 'xmpp', add env_enablement_fn + cron_deliver_env_var 2026-05-08 10:16:34 +07:00
README.md feat: migrate to pluggable platform plugin (Hermes v0.12.0) 2026-05-01 22:19:53 +07:00

README.md

hermes-xmpp-gateway

Native XMPP platform adapter for Hermes Agent v0.12.0+, built with slixmpp.

Connects Hermes to any XMPP server (tested with ejabberd) over direct C2S TCP as a pluggable platform plugin — drop it into plugins/platforms/xmpp/ and it auto-loads with zero core-file patches.

Features

  • Drop-in plugin — no patches to gateway/config.py, gateway/run.py, or toolsets.py
  • Direct C2S TCP connection (plaintext on trusted internal vLAN)
  • XEP-0085 chat state notifications (typing indicator — composing/paused)
  • XEP-0308 Last Message Correction (edit_message support)
  • XEP-0199 keepalive pings (60s interval)
  • Configurable allowed-users list via env var
  • Auto-reconnect on unexpected disconnect
  • Long message chunking (10 000 char limit)
  • Auto-generates hermes-xmpp toolset via plugin registry

Requirements

pip install slixmpp

Installation (Hermes Agent v0.12.0+)

Copy the three files into your Hermes Agent install:

plugins/platforms/xmpp/
├── __init__.py
├── adapter.py
└── plugin.yaml

That's it. The gateway discovers and loads bundled platform plugins at startup via _scan_bundled_plugin_platforms(). Set XMPP_JID and XMPP_PASSWORD in your .env and the platform auto-enables through the generic plugin startup pass in _apply_env_overrides().

Configuration

Set in ~/.hermes/.env:

Variable Required Description
XMPP_JID ✅ Bot's JID (e.g. hermes@example.com)
XMPP_PASSWORD ✅ Bot's XMPP password
XMPP_ALLOWED_USERS ❌ Comma-separated JIDs allowed to chat (empty = allow all)
XMPP_HOME_CHANNEL ❌ JID to announce startup to
XMPP_HOME_CHANNEL_NAME ❌ Display name for home channel

No config.yaml entry needed — the plugin's check_requirements() is called automatically.

How it works

slixmpp normally requires TLS for PLAIN auth. On a trusted internal vLAN, we override the security callback after init_plugins() to allow plaintext PLAIN auth — no certificate setup needed.

The adapter:

  1. Connects to the XMPP server via direct TCP (default: roiarthurb.xyz:5222)
  2. Authenticates using PLAIN (no TLS — trusted vLAN only)
  3. Registers presence and fetches the roster
  4. Bridges incoming chat messages to Hermes' gateway message handler
  5. Sends replies as plain text stanzas, chunked at 10 000 chars
  6. Sends XEP-0085 composing state while Hermes is processing
  7. Sends XEP-0308 corrections for edited messages

Compatibility

Hermes version Adapter version Installation method
v0.12.0+ 2.1.0 (this repo) Plugin (plugins/platforms/xmpp/)
v0.5.0–v0.11.x 2.0.0 Patch (gateway/platforms/xmpp.py + 4 core-file edits)