Guide
Connect SimpleX Chat to Your AI Agent
SimpleX goes further than most private messengers: there are no user IDs at all, not even a random one. That design shapes the whole setup, so it is worth understanding before you start.
What Makes SimpleX Different
Signal identifies you by phone number, Matrix by a username. SimpleX identifies you by nothing — connections are made through one-time invitation links rather than a directory, so there is no account to look up and no identifier to leak.
The practical consequence for a bot: nobody can find your agent by searching. Every conversation starts from an invitation link that you share deliberately. That is excellent for privacy and it means there is no discovery path to rely on.
The Bridge
Hermes talks to SimpleX through the simplex-chat daemon over a WebSocket. So, as with Signal, there is a piece of software that must be installed and kept running alongside your agent — the messenger has no bot API of its own.
Install the Daemon
From your instance's Web Terminal, install the simplex-chat binary for Linux and start it in WebSocket mode. Install it onto your persistent volume rather than a temporary path, so it survives a container rebuild:
# install into /opt/data so it persists
mkdir -p /opt/data/simplex/binYou will also need the Python websockets package available to the gateway if it is not already present.
Configure Hermes
Run the guided setup and pick SimpleX:
hermes gateway setupOr set it directly:
SIMPLEX_WS_URL=ws://127.0.0.1:5225
SIMPLEX_ALLOWED_USERS=<contact-id-1>,<contact-id-2>The allowed-users list is how you keep the agent to people you have actually invited. Fill it in once you know the contact IDs of the people who connected.
Keep the Daemon Running
A hand-started daemon dies with the next restart and SimpleX silently goes quiet. Use a gateway startup hook, which lives on your persistent volume and fires whenever the gateway starts. The Signal guide shows the same pattern in full — create a hook directory with a manifest subscribing to gateway:startup and a handler that launches the daemon if it is not already listening.
Connect Someone
Create an invitation from the daemon and open it in your SimpleX app. Once connected, message the agent and it replies in that conversation. Share invitations only with people you intend to give access — an invitation link is the access.
Troubleshooting
- The agent never responds. The daemon is not running or the WebSocket address is wrong. Check the daemon first, before anything in Hermes.
- It worked, then stopped after a restart. The startup hook is missing — this is the single most common failure with daemon-based channels.
- An invitation link does not work twice. That is by design; generate a new one per contact.
- It ignores a specific person. Their contact ID is not in the allowed-users list.
Need a Hand?
Contact support from your dashboard and we will set the daemon and the hook up for you. You will still create and share the invitations yourself.