Mautrix Bridges

https://docs.mau.fi/bridges
Admin
Mautrix Bridges provides documentation for various Matrix bridges developed by mau.fi, enabling...
Tokens:40,460
Snippets:319
Trust Score:7.4
Update:14 hours ago
Show doc for...
Tokens:
Raw
### Run the bridge

Source: https://docs.mau.fi/bridges/go/imessage/mac/setup.html

Command to start the bridge after configuration and registration.

```bash
./mautrix-imessage
```

--------------------------------

### Run the bridge

Source: https://docs.mau.fi/bridges/python/setup.html

Starts the bridge after registration. Run this after registering the bridge on your homeserver.

```bash
python -m mautrix_$bridge
```

--------------------------------

### Load v4l2loopback module

Source: https://docs.mau.fi/bridges/go/whatsapp/android-vm-setup.html

Install and load the v4l2loopback module to create a virtual camera device.

```shell
modprobe v4l2loopback
```

--------------------------------

### Install bridge with pip

Source: https://docs.mau.fi/bridges/python/setup.html

Installs the bridge with all optional dependencies. The [all] extra includes end-to-bridge encryption, which requires libolm3. Use this command for a release version.

```bash
pip install --upgrade mautrix-$bridge[all]
```

--------------------------------

### Install Android SDK components for AVD

Source: https://docs.mau.fi/bridges/go/whatsapp/android-vm-setup.html

Install required SDK components using sdkmanager. Change version and architecture as required; use x86 target if KVM is supported, otherwise ARM targets.

```shell
./tools/bin/sdkmanager --install platform-tools emulator
./tools/bin/sdkmanager --install "platforms;android-24"
./tools/bin/sdkmanager --install "system-images;android-24;default;armeabi-v7a"
```

--------------------------------

### Install bridge from master branch

Source: https://docs.mau.fi/bridges/python/setup.html

Installs the bridge from the master branch instead of a release. Use this when you want the latest development version.

```bash
pip install --upgrade mautrix-$bridge[all]@git+https://github.com/mautrix/$bridge.git
```

--------------------------------

### Install python-olm from GitLab PyPI registry

Source: https://docs.mau.fi/bridges/python/optional-dependencies.html

Use this command to install python-olm without dev headers, pulling a pre-compiled package from gitlab.matrix.org's PyPI registry. This method is untested and may not work.

```shell
pip install python-olm --extra-index-url https://gitlab.matrix.org/api/v4/projects/27/packages/pypi/simple
```

--------------------------------

### Run Android emulator headless

Source: https://docs.mau.fi/bridges/go/whatsapp/android-vm-setup.html

Starts the Android emulator without audio or window, suitable for headless environments. Replace AVD_NAME with your AVD name and add any desired options.

```shell
./emulator/emulator -avd AVD_NAME -no-audio -no-window [options]
```

--------------------------------

### Create virtual environment with virtualenv

Source: https://docs.mau.fi/bridges/python/setup.html

Creates a virtual environment in the current directory (note the trailing dot). Do not use a subdirectory for the virtualenv in production; the pip install step places required files at the root.

```bash
virtualenv -p /usr/bin/python3 .
```

--------------------------------

### Boot AVD with emulator options

Source: https://docs.mau.fi/bridges/go/whatsapp/android-vm-setup.html

Boot the AVD using the emulator command line. Options include -no-audio, -no-window, -show-kernel, -no-snapshot, and -memory.

```bash
./emulator/emulator -avd AVD_NAME [options]
```

--------------------------------

### Fix Brooklyn config permission denied error

Source: https://docs.mau.fi/bridges/go/imessage/ios/setup.html

Run this command over SSH on the iPhone after installing OpenSSH via Cydia. It changes permissions on the mautrix-imessage directory to allow Brooklyn to write the config file.

```bash
chmod 777 /var/mobile/Documents/mautrix-imessage-armv7
```

--------------------------------

### Generate QR code for Brooklyn config URL

Source: https://docs.mau.fi/bridges/go/imessage/ios/setup.html

Use this command to generate a QR code from the config URL. The URL must be lowercase due to a Brooklyn bug. The example uses basic auth credentials in the URL.

```bash
echo -n https://user:pass@example.com/your-config.yaml | qrencode -t ansiutf8
```

--------------------------------

### Password login to get access token

Source: https://docs.mau.fi/bridges/general/double-puppeting.html

Use this curl command to log in to the homeserver with a password and obtain an access token for manual double puppeting. The `initial_device_display_name` field can be changed to something more descriptive. This method is a fallback when automatic double puppeting is not available.

```shell
$ curl -XPOST -d '{"type":"m.login.password","identifier":{"type": "m.id.user", "user": "example"},"password":"wordpass","initial_device_display_name":"a fancy bridge"}' https://example.com/_matrix/client/v3/login
```

--------------------------------

### Run mautrix bridge container to generate config

Source: https://docs.mau.fi/bridges/general/docker-setup.html

First run of the container creates a config file. Mounts the current working directory as /data; the image chowns /data to UID 1337, so run from the correct directory. Replace $bridgerepo and <version> with the bridge repo and desired tag (e.g. latest or v25.11).

```bash
docker run --rm -v `pwd`:/data:z dock.mau.dev/mautrix/$bridgerepo:<version>
```

--------------------------------

### Feed desktop into virtual webcam with ffmpeg

Source: https://docs.mau.fi/bridges/go/whatsapp/android-vm-setup.html

Use ffmpeg to feed your desktop into the virtual webcam device /dev/video0.

```shell
ffmpeg -f x11grab -s 640x480 -i :0.0+10,20 -vf format=pix_fmts=yuv420p -f v4l2 /dev/video0
```

--------------------------------

### Run emulator with webcam0 back camera

Source: https://docs.mau.fi/bridges/go/whatsapp/android-vm-setup.html

Set the back-camera mode to webcam0 when running the emulator from command line.

```shell
./emulator/emulator -avd AVD_NAME -camera-back webcam0
```

--------------------------------

### Start WhatsApp main activity via adb

Source: https://docs.mau.fi/bridges/go/whatsapp/android-vm-setup.html

Reboots or starts WhatsApp's main activity if the AVD becomes unresponsive. Use the adb variant to target a specific device serial.

```shell
am start -n 'com.whatsapp/.HomeActivity'
```

```shell
adb [-s DEVICE_SERIAL] shell am start -n 'com.whatsapp/.HomeActivity'
```

--------------------------------

### Build the Instagram bridge in mautrix-meta

Source: https://docs.mau.fi/bridges/go/setup.html

Builds the Instagram bridge in the mautrix-meta repository instead of using the default build.sh.

```bash
./build-ig.sh
```

--------------------------------

### systemd service file for mautrix bridge

Source: https://docs.mau.fi/bridges/python/setup.html

Systemd unit file to run the bridge as a service. Place at /etc/systemd/system/mautrix-$bridge.service. WorkingDirectory is set to ~ (the user's home) unless config.yaml is elsewhere; ExecStart runs the bridge Python module. Replace $bridge with the actual bridge name.

```ini
[Unit]
Description=mautrix-$bridge bridge

[Service]
# N.B. If you didn't create a user with the correct home directory, set this
#      to the directory where config.yaml is (e.g. /opt/mautrix-$bridge).
WorkingDirectory=~
ExecStart=/opt/mautrix-$bridge/bin/python -m mautrix_$bridge
User=mautrix-$bridge

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Activate virtual environment

Source: https://docs.mau.fi/bridges/python/setup.html

Activates the virtual environment created in the current directory. Required before installing or running the bridge.

```bash
source ./bin/activate
```

--------------------------------

### docker-compose.yml for mautrix bridge

Source: https://docs.mau.fi/bridges/general/docker-setup.html

Example docker-compose.yml for running a mautrix bridge. The image tag uses a placeholder for the bridge repository and version. The Instagram bridge uses `meta:ig-<version>` instead of `instagram:<version>`. Commented sections cover networking with Synapse when it runs outside Docker or in a different network.

```yaml
version: "3.7"

services:
  mautrix-$bridge:
    container_name: mautrix-$bridge
    image: dock.mau.dev/mautrix/$bridgerepo:<version>
    restart: unless-stopped
    volumes:
    - .:/data

    # If you put the service above in the same docker-compose as the homeserver,
    # ignore the parts below. Otherwise, see below for configuring networking.

    # If synapse is running outside of docker, you'll need to expose the port.
    # Note that in most cases you should either run everything inside docker
    # or everything outside docker, rather than mixing docker things with
    # non-docker things.
    #ports:
    #- "$bridgeport:$bridgeport"
    # You'll also probably want this so the bridge can reach Synapse directly
    # using something like `http://host.docker.internal:8008` as the address:
    #extra_hosts:
    #- "host.docker.internal:host-gateway"

    # If synapse is in a different network, then add this container to that network.
    #networks:
    #- synapsenet
# This is also a part of the networks thing above
#networks:
#  synapsenet:
#    external:
#      name: synapsenet
```

--------------------------------

### systemd service file for mautrix bridge

Source: https://docs.mau.fi/bridges/go/setup.html

Place this file at /etc/systemd/system/mautrix-$bridge.service. It runs the bridge as the mautrix-$bridge user, with optional hardening commented out. The service restarts on failure after 30 seconds.

```ini
[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
```

--------------------------------

### Connect to manhole with rlwrap

Source: https://docs.mau.fi/bridges/python/manhole.html

Use rlwrap with netcat to get a nicer prompt. This can be run in a normal shell.

```bash
rlwrap nc -NU /var/tmp/mautrix-telegram.manhole
```

--------------------------------

### Disable encryption with nocrypto tag

Source: https://docs.mau.fi/bridges/go/setup.html

Compiles the bridge without end-to-bridge encryption. Use this if you do not have a C/C++ compiler and the Olm dev headers (libolm-dev on debian-based distros) installed.

```bash
./build.sh -tags nocrypto
```

--------------------------------

### Caddy reverse proxy configuration for Discord media

Source: https://docs.mau.fi/bridges/go/discord/direct-media.html

Caddy configuration to proxy Discord media downloads and thumbnails through your own domain. Replace `discord-media.mau.dev/` with `example.com/discord_` in the patterns. The `discord_` prefix avoids conflicts with other media on your domain. Handles downloads via cdn.discordapp.com and thumbnails via media.discordapp.net.

```Caddyfile
matrix.example.com {
	handle /_matrix/media/*/download/example.com/discord_* {
		header Access-Control-Allow-Origin *
		# Remove path prefix
		uri path_regexp ^/_matrix/media/.+/download/example\.com/discord_ /
		# The mxc patterns use | instead of /, so replace it first turning it into attachments/1234/5678/filename.png
		uri replace "%7C" /
		reverse_proxy {
			# reverse_proxy automatically includes the uri, so no {uri} at the end
			to https://cdn.discordapp.com
			# Caddy doesn't set the Host header automatically when reverse proxying
			# (because usually reverse proxies are local and don't care about Host headers)
			header_up Host cdn.discordapp.com
		}
	}
	# Do the same for thumbnails, but redirect to media.discordapp.net (which is Discord's thumbnailing server, and happens to use similar width/height params as Matrix)
	# Alternatively, you can point this at cdn.discordapp.com too. Clients shouldn't mind even if they get a bigger image than they asked for.
	handle /_matrix/media/*/thumbnail/example.com/discord_* {
		header Access-Control-Allow-Origin *
		uri path_regexp ^/_matrix/media/.+/thumbnail/example\.com/discord_ /
		uri replace "%7C" /
		reverse_proxy {
			to https://media.discordapp.net
			header_up Host media.discordapp.net
		}
	}
	handle /_matrix/* {
		reverse_proxy http://localhost:8008
	}
}
```
Tokens:
Raw