Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Go bridge setup

Please select a bridge above. If you don't select a bridge, you'll have to manually replace occurrences of $bridge with the correct name before running commands. The selector requires JavaScript to replace text.

This page contains instructions for setting up the bridge by running the executable yourself. You may also want to look at the other ways to run the bridge:

Please note that everything in these docs are meant for server admins who want to self-host the bridge. If you're just looking to use the bridges, check out Beeper, which provides fully managed instances of all of these bridges.

If you need help with setting up the bridge, you can ask in the Matrix room: #$bridge:maunium.net. For help with setting up other parts like the homeserver that aren't the bridge, refer to their documentation to find support rooms.

Step 0: Requirements

  • A Matrix homeserver that supports application services (e.g. Synapse). You need access to register an appservice, which usually involves editing the homeserver config file.
  • A PostgreSQL server, v10 or higher (which you should already have for Synapse).
    • Make sure you don't share databases between unrelated programs. Shared postgres instance is fine, but shared database is not.
  • mautrix-whatsapp: A WhatsApp client running on a phone (both physical and virtual phones work).
  • mautrix-signal: A Signal client that can add linked devices (both official mobile apps and some unofficial clients like signal-cli work).
  • mautrix-signal: ffmpeg (if you want to send/receive voice messages).
  • mautrix-whatsapp: ffmpeg (if you want to send gifs from Matrix).
  • mautrix-discord: LottieConverter if you want to receive animated stickers.
  • mautrix-gvoice: Sending messages with non-workspace accounts requires having Electron installed, such that the bridge can run the electron binary in headless mode.

If you want to compile the bridge manually (which is not required), you'll also need:

  • Go 1.23+ (download & installation instructions at https://go.dev/doc/install).
  • libolm3 with dev headers and a C/C++ compiler (if you want end-to-bridge encryption).
  • mautrix-signal: Rust, Cargo, libclang-dev and protoc (if you want to compile libsignal yourself).

Step 1: Installation

You may either compile the bridge manually or download a prebuilt executable from the mau.dev CI or GitHub releases. Prebuilt executables are the simplest option, as they don't require having Go nor libolm installed.

Option 1: Downloading a prebuilt executable from CI

  1. Download the relevant artifacts:
  2. Extract the downloaded zip file into a new directory.

Option 2: Downloading a release

  1. Go to https://github.com/mautrix/$bridge/releases
  2. Download the binary for the architecture you want and save it in a new directory.

Option 3: Compiling manually

  1. Clone the repo with git clone https://github.com/mautrix/$bridge.git mautrix-$bridge
  2. Enter the directory (cd mautrix-$bridge)
  3. Run ./build.sh to fetch Go dependencies and compile (build.sh will simply call go build with some additional flags).
    • If you want end-to-bridge encryption, make sure you have a C/C++ compiler and the Olm dev headers (libolm-dev on debian-based distros) installed.
    • If not, use ./build.sh -tags nocrypto to disable encryption.
      • Note: signal's build.sh script doesn't support extra arguments yet, so you have to use build-go.sh manually after building libsignal-ffi.a.
    • As an experimental feature, you can also use -tags goolm to use a pure Go reimplementation of libolm. Encryption can be supported without a C compiler or Olm dev headers with this method.

For mautrix-signal, if you don't want to compile libsignal yourself, you can download a precompiled libsignal_ffi.a from the mau.dev CI and place it in /usr/local/lib (or some other directory set in LIBRARY_PATH). Download links: Linux amd64, Linux arm64, macOS arm64

Step 2: Configuring and running

  1. Use ./mautrix-$bridge -e to generate an example config and save it to config.yaml.
    • Discord is still using the legacy architecture which doesn't have the -e flag, so just manually copy example-config.yaml from the repo to config.yaml.
  2. Update the config to your liking. See the initial bridge config page for recommendations.
  3. Generate the appservice registration file by running ./mautrix-$bridge -g.
    • You can use the -c and -r flags to change the location of the config and registration files. They default to config.yaml and registration.yaml respectively.
  4. Register the bridge on your homeserver (see Registering appservices).
  5. Run the bridge with ./mautrix-$bridge.

Updating

If you compiled manually, pull changes with git pull and recompile with ./build.sh.

If you downloaded a prebuilt executable, simply download a new one and replace the old one.

Finally, start the bridge again.

systemd service

  1. Create a user for the bridge: 
    $ sudo adduser --system mautrix-$bridge --home /opt/mautrix-$bridge
  2. Follow the normal setup instructions above. Make sure you use that user and home directory for the bridge.
  3. Create a systemd service file at /etc/systemd/system/mautrix-$bridge.service: 
    [Unit]
Description=mautrix-$bridge bridge

[Service]
Type=exec
User=mautrix-$bridge
WorkingDirectory=/opt/mautrix-$bridge
ExecStart=/opt/mautrix-$bridge/mautrix-$bridge
Restart=on-failure
RestartSec=30s

# Optional hardening to improve security
ReadWritePaths=/opt/mautrix-$bridge
NoNewPrivileges=yes
# This may cause issues with libsignal.
# Should be safe for other bridges
#MemoryDenyWriteExecute=true
PrivateDevices=yes
PrivateTmp=yes
ProtectHome=yes
ProtectSystem=strict
ProtectControlGroups=true
RestrictSUIDSGID=true
RestrictRealtime=true
LockPersonality=true
ProtectKernelLogs=true
ProtectKernelTunables=true
ProtectHostname=true
ProtectKernelModules=true
PrivateUsers=true
ProtectClock=true
SystemCallArchitectures=native
SystemCallErrorNumber=EPERM
SystemCallFilter=@system-service

[Install]
WantedBy=multi-user.target