mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-05-18 04:41:56 +00:00

Mibayy 09d9724a09 feat(gateway): add SimpleX Chat platform plugin

SimpleX Chat (https://simplex.chat) is a private, decentralised messenger
with no persistent user IDs — every contact is identified by an opaque
internal ID generated at connection time. This adds it as a Hermes
gateway platform via the plugin system.

The adapter connects to a local simplex-chat daemon via WebSocket,
listens for inbound messages, and sends replies. Originally proposed in
PR #2558 as a core-modifying integration; reshaped here as a self-
contained plugin under plugins/platforms/simplex/ with no edits to any
core file. Discovery is filesystem-based (scanned by gateway.config),
and the platform identity is resolved on demand via Platform("simplex").

Plugin contract:
- check_requirements() requires SIMPLEX_WS_URL AND the websockets package
- validate_config() / is_connected() accept env or config.yaml input
- _env_enablement() seeds PlatformConfig.extra (ws_url + home_channel)
- _standalone_send() supports out-of-process cron delivery
- interactive_setup() provides a stdin wizard for hermes gateway setup
- register() wires the adapter into the registry with required_env,
  install_hint, cron_deliver_env_var, allowed_users_env, and a
  platform_hint for the LLM.

Lazy dependency: the websockets Python package is imported inside the
functions that need it. The plugin is importable and discoverable even
when websockets is missing — check_requirements() simply returns False
until `pip install websockets` is run. No new pyproject extras are
introduced.

Environment variables:
  SIMPLEX_WS_URL             WebSocket URL of the daemon (required)
  SIMPLEX_ALLOWED_USERS      Comma-separated allowed contact IDs
  SIMPLEX_ALLOW_ALL_USERS    Set true to allow all contacts
  SIMPLEX_HOME_CHANNEL       Default contact for cron delivery
  SIMPLEX_HOME_CHANNEL_NAME  Human label for the home channel

Closes #2557.

2026-05-15 01:41:30 -07:00

3.2 KiB

Raw Blame History

SimpleX Chat

SimpleX Chat is a private, decentralised messaging platform where users own their contacts and groups. Unlike other platforms, SimpleX assigns no persistent user IDs — every contact is identified by an opaque internal ID generated at connection time, which makes it one of the most private messengers available.

Prerequisites

The simplex-chat CLI installed and running as a daemon
Python package websockets (pip install websockets)

Install simplex-chat

Download the latest release from the simplex-chat GitHub releases page, or via Docker:

# Linux / macOS binary
curl -L https://github.com/simplex-chat/simplex-chat/releases/latest/download/simplex-chat-ubuntu-22_04-x86-64 -o simplex-chat
chmod +x simplex-chat

# Or Docker
docker run -p 5225:5225 simplexchat/simplex-chat -p 5225

Start the daemon

simplex-chat -p 5225

The daemon listens on WebSocket at ws://127.0.0.1:5225 by default.

Configure Hermes

Via setup wizard

hermes setup gateway

Select SimpleX Chat and follow the prompts.

Via environment variables

Add these to ~/.hermes/.env:

SIMPLEX_WS_URL=ws://127.0.0.1:5225
SIMPLEX_ALLOWED_USERS=<contact-id-1>,<contact-id-2>
SIMPLEX_HOME_CHANNEL=<contact-id>

Variable	Required	Description
`SIMPLEX_WS_URL`	Yes	WebSocket URL of the simplex-chat daemon
`SIMPLEX_ALLOWED_USERS`	Recommended	Comma-separated contact IDs allowed to use the agent
`SIMPLEX_ALLOW_ALL_USERS`	Optional	Set `true` to allow every contact (use carefully)
`SIMPLEX_HOME_CHANNEL`	Optional	Default contact ID for cron job delivery
`SIMPLEX_HOME_CHANNEL_NAME`	Optional	Human label for the home channel

Find your contact ID

After starting the daemon, open a conversation with your agent contact. The contact ID will appear in session logs or via hermes send_message action=list.

Authorization

By default all contacts are denied. You must either:

Set SIMPLEX_ALLOWED_USERS to a comma-separated list of contact IDs, or
Use DM pairing — send any message to the bot and it will reply with a pairing code. Enter that code via hermes gateway pair.

Using SimpleX with cron jobs

cronjob(
    action="create",
    schedule="every 1h",
    deliver="simplex",          # uses SIMPLEX_HOME_CHANNEL
    prompt="Check for alerts and summarise."
)

Or target a specific contact:

send_message(target="simplex:<contact-id>", message="Done!")

Privacy notes

SimpleX never reveals phone numbers or email addresses — contacts use opaque IDs
The connection between Hermes and the daemon is local WebSocket (ws://127.0.0.1:5225) — no data leaves your machine
Messages are end-to-end encrypted by the SimpleX protocol before reaching the daemon

Troubleshooting

"Cannot reach daemon" — Ensure simplex-chat -p 5225 is running and the port matches SIMPLEX_WS_URL.

"websockets not installed" — Run pip install websockets.

Messages not received — Check that the contact's ID is in SIMPLEX_ALLOWED_USERS or approve them via DM pairing.

3.2 KiB Raw Blame History