Skip to main content
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.
Run mibyan gateway setup and pick SimpleX for a guided walk-through.

​
Prerequisites

  • The simplex-chat CLI installed and running as a daemon
  • Python package websockets (mibyan pm repair)

​
Install simplex-chat

Download the latest release from the simplex-chat GitHub releases page:
The SimpleX Chat project does not publish a prebuilt Docker image for the chat client; to run it under Docker, build from source from the simplex-chat repository.

​
Start the daemon

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

​
Configure Mibyan

​
Via setup wizard

Select SimpleX Chat and follow the prompts.

​
Via environment variables

Add these to ~/.mibyan/.env:

​
Find your contact ID

After starting the daemon, open a conversation with your agent contact. The numeric contactId appears in session logs (or run /contacts in the daemon). SIMPLEX_ALLOWED_USERS matches only this ID: display names are chosen by the contact and can collide, so they are ignored.

​
Authorization

By default all contacts are denied. You must either:
  1. Set SIMPLEX_ALLOWED_USERS to a comma-separated list of numeric contactIds (e.g. SIMPLEX_ALLOWED_USERS=4,9), or
  2. Use DM pairing — send any message to the bot and it will reply with a pairing code. Enter that code via mibyan pairing approve simplex <CODE>.

​
Group chats

By default the adapter ignores group messages — a bot in a group otherwise processes every member’s traffic. Opt-in explicitly:
Address groups by prefixing the chat ID with group:, e.g. simplex:group:12 as a cron deliver= target or in a mibyan send call.

​
Sending with mibyan send

SimpleX works as a standalone send target — the daemon must be running, but a live gateway is not required for plain text:
While the gateway is running, the adapter enumerates your contacts and allowed groups into the channel directory (refreshed every 5 minutes), so mibyan send --list shows them by name. Before the first gateway run the platform still appears in --list with a “no channels discovered yet” hint — direct targets like the ones above work regardless.

​
Attachments

The adapter supports native SimpleX attachments in both directions:
  • Inbound — incoming images, voice notes, and files are accepted via the daemon’s XFTP flow (rcvFileDescrReady → /freceive → wait for rcvFileComplete) and surfaced as MessageEvent.media_urls with the appropriate MessageType (PHOTO, VOICE, TEXT + document).
  • Outbound — send_image_file, send_voice, send_document, and send_video all use the structured /_send form with filePath, so the receiving SimpleX client renders images inline and plays voice notes inline rather than offering them as downloads.
Agent replies can also embed MEDIA:/path/to/file tags in plain text — the adapter strips the tag from the body and sends the file as either a voice note (audio extensions) or a document.

​
Using SimpleX with cron jobs

Or target a specific contact via the cron job’s deliver: field, or from a shell script with the mibyan send CLI:

​
Privacy notes

  • SimpleX never reveals phone numbers or email addresses — contacts use opaque IDs
  • The connection between Mibyan 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 mibyan pm repair. Messages not received — Check that the contact’s ID is in SIMPLEX_ALLOWED_USERS or approve them via DM pairing.