AI GENERATED README

Session ↔ SimpleX group bridge

Relays text messages between a private Session group (Groups v2) and a private SimpleX group. A single bot identity joins both groups as a regular member and reposts each message on the other side with the sender's name (alice: hello).

Requirements

• Bun ≥ 1.3
• linux-x64 with glibc ≥ 2.38 (for the prebuilt native addon; see below for other platforms)

Install and test

bun install
bun run test                # unit tests, no network
bun run typecheck
E2E_LIVE=1 bun run test:e2e # end-to-end on the live Session and SimpleX networks

Setup

Everything the bot is lives in deploy/: mnemonic.txt is its Session identity and bot-simplex-db/ is its SimpleX identity, which has no recovery phrase. Back up deploy/, keep it private, and never commit it.

Run these from the repository root, after bun install.

1. Create the bot's identity (once):

bun bridge/src/cli.ts new-identity --mnemonic-file deploy/mnemonic.txt

2. Start onboarding in a terminal and leave it running:

bun bridge/src/cli.ts onboard --mnemonic-file deploy/mnemonic.txt --simplex-db deploy/bot-simplex-db/bot

It prints the bot's Session ID and SimpleX address, then waits until the bot is in a group on each side.

3. Add the bot to your groups while onboard is running:

• SimpleX: connect to the bot's address, then add the bot to your group. The bot accepts both automatically.
• Session: as a group admin, add the bot's Session ID to your group.

4. Accept the Session invitation in a second terminal:

bun bridge/src/cli.ts invites --mnemonic-file deploy/mnemonic.txt --simplex-db deploy/bot-simplex-db/bot --accept

If it reports no pending invitations, wait a minute and run it again. Once the bot is in a group on both sides, onboard in the first terminal exits.

5. List the group ids:

bun bridge/src/cli.ts channels --mnemonic-file deploy/mnemonic.txt --simplex-db deploy/bot-simplex-db/bot

6. Start relaying, using the --session-group and --simplex-group values printed by channels:

bun bridge/src/cli.ts run --mnemonic-file deploy/mnemonic.txt --simplex-db deploy/bot-simplex-db/bot \
  --session-group 03abc… --simplex-group 2

Add --dry-run to log what would be relayed without posting anything. Stop with Ctrl-C.

Only one process may use the SimpleX database at a time: make sure onboard has exited before run, and never run the bridge on two machines at once. Run bun bridge/src/cli.ts with no arguments to see all options.

Running as a service

Complete the setup above first, then stop run. Both options below need bun install to have been run on a linux-x64 machine: the node_modules it produces is shipped as-is.

Docker Compose

cp ops/bridge.env.example ops/.env

Set SESSION_GROUP and SIMPLEX_GROUP in ops/.env. The container runs as your user so it can read and write deploy/:

printf 'BRIDGE_UID=%s\nBRIDGE_GID=%s\n' "$(id -u)" "$(id -g)" >> ops/.env
docker compose -f ops/docker-compose.yml up -d --build
docker compose -f ops/docker-compose.yml logs -f

systemd on a remote host

The unit expects a user named debian with the bridge in /home/debian/bridge. If your host differs, edit User, Group and the /home/debian paths in ops/session-simplex-bridge.service before copying it.

cp ops/bridge.env.example deploy/bridge.env

Set SESSION_GROUP and SIMPLEX_GROUP in deploy/bridge.env, then ship the code and the identity (this installs Bun on the host if missing):

ops/deploy.sh debian@your-host --identity

On the host:

sudo cp ~/bridge/ops/session-simplex-bridge.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now session-simplex-bridge
~/bridge/ops/healthcheck.sh

For later code-only updates run ops/deploy.sh debian@your-host, which restarts the unit.

Native addon

The Session side uses libsession-util-nodejs. A prebuilt linux-x64 build (v0.6.17) and its type declarations are committed in session-groups/vendor/prebuilt/. To rebuild for another platform or version (needs git, a C++ toolchain and network access):

bash session-groups/vendor/rebuild.sh   # LIBSESSION_REF=v0.6.x to override

Limitations

• Text only. Attachments, reactions and edits are not relayed.
• Messages sent while the bridge is offline are not relayed, and history is never replayed.
• A message that still fails to send after the network layer's retries is dropped.
• All relayed messages come from the bot account; the author's name is in the message text.
• The bot must run at least every 30 days, or it loses its Session group membership and needs a new invitation.
• Memory use is around 400 MB.

License

AGPL-3.0. Depends on simplex-chat (AGPL-3.0) and redistributes a build of libsession-util (GPL-3.0).