General purpose puppeting bridges using libpurple and other backends.
This bridge is in very active development currently and intended mainly for experimentation and evaluation purposes.
This has been tested to work on
Node.JS v10 and
NOTE: You must read this README carefully as simply installing required dependencies may NOT be enough for some backends
This bridge features multiple backends for spinning up bridges on different types of network. The following are supported:
xmpp.jsSupported on Docker Designed to bridge to XMPP networks directly, without purple. Good for setups requiring an extremely scalable XMPP bridge. Uses XMPP components.
node-purpleUses libpurple to bridge to a number of networks supported by libpurple2. Good for simple bridges for a small number of users, or for bridging to less available protocols.
- WARNING: If using
node-purplethen you MUST install the dependency:
npm i node-purple
- WARNING: If using
If you wish to use the
xmpp.js backend, you can go straight ahead and use the provided Dockerfile
to build the bridge. You can build the docker image with
docker build -t bifrost:latest and then
run the image with:
docker run -v /your/path/to/data:/data bifrost:latest -p 5000:9555.
An image is available on Dockerhub.
Things to note
- Make sure you store your
- You should configure your
roomStoreFileto point to files inside
- The intenal port for the bridge is
5000, you should map this to an external port in docker.
- Be careful not to leave any config options pointing to
localhostas they will not resolve inside docker.
- The exception to this rule is
bridge.domain, which MUST be your homeserver's URL.
node-purple to compile correctly, you will need (for Debian):
You can install this on Ubuntu/Debian using
sudo apt install build-essential libuv1.
Instructions for other distributions will come soon.
Installing & Configuring
NOTE: You must carefully read the config.sample.yaml and use the bits appropriate for you. Do NOT copy and paste it verbatim as it won't work.
npm install # Install dependencies npm run build # Build files cp config.sample.yaml config.yaml # ... Set the domain name, homeserver url, and then review the rest of the config sed -i "s/domain: \"localhost\"/domain: \"$YOUR_MATRIX_DOMAIN\"/g" config.yaml
You must also generate a registration file:
npm run genreg -- -u http://localhost:9555 # Set listener url here.
This file should be accessible by your homeserver, which will use this file to get the correct url and tokens to push events to.
For Synapse, this can be done by:
homeserver.yamlto include the full path of your registration file generated above.
app_service_config_files: - ".../bifrost-registration.yaml"
- Restart synapse, if it is running (
XMPP bridge using the xmpp.js backend
After completing all the above, you should do the following:
- Set the
- Possibly change the registration file alias and user regexes
_purple_. Make sure to replicate those changes in
- Setup your XMPP server to support a new component.
- Setup the
purple.backendOptsoptions for the new component.
- Setup autoregistration and portals in
start.sh script will auto preload the build libpurple library and offers a better experience than the system libraries in most cases. Pleas remember to modify the port in the script if you are using a different port.
If you are not using the
node-purple backend, you can just start the service with:
npm run start -- -p 9555
Binding purple accounts to a Matrix User
The bridge won't do much unless it has accounts to bind. Due to the infancy of the bridge, we still use
for the location of all the accounts. Our advice is to create the accounts you want to use on your local machine with Pidgin, and
then copy the
accounts.xml file to the bridge (where you should be copying the file to
Once you have started the bridge, you can instruct it to bind by starting a conversation with the bridge user and
accounts add-existing $PROTOCOL $USERNAME where the protocol and username are given in the
You should also run
accounts enable $PROTOCOL $USERNAME to enable the account for the bridge, and then it should connect automatically.
Bridging XMPP room (on node-purple)
Connect to your matrix server and open a chat with
accounts add-existing prpl-jabber $USERNAME@$XMPP_SERVER/$CLIENT_NAME accounts enable prpl-jabber $USERNAME@$XMPP_SERVER/$CLIENT_NAME accounts join xmpp $ROOM $XMPP_SERVER
My bridge crashed with a segfault
node-purple rewrite is still not quite bugfree and we are working hard to iron out the kinks in it. We ask that you report
if certain purple plugins cause more crashes, or if anything in particular lead up to it.
Running the tests is as simple as doing
npm run test