beeper/bridge-manager

A tool for running self-hosted bridges with the Beeper Matrix server.

Beeper Bridge Manager

A tool for running self-hosted bridges with the Beeper Matrix server.

The primary use case is running custom/3rd-party bridges with Beeper. You can connect any^† standard Matrix application service to your Beeper account without having to self-host a whole Matrix homeserver. Note that if you run 3rd party bridges that don't support end-to-bridge encryption, message contents will be visible to Beeper servers.

_{†caveat: hungryserv does not implement the entire Matrix client-server API, so it's possible some bridges won't work - you can report such cases in the self-hosting support room linked below or in GitHub issues here}

You can also self-host the official bridges for maximum security using this tool (so that message re-encryption happens on a machine you control rather than on Beeper servers).

Note

Self-hosted bridges are not entitled to the usual level of customer support on Beeper. If you need help with self-hosting bridges using this tool, please join #self-hosting:beeper.com instead of asking in your support room.

Usage

1. Download the latest binary from GitHub releases or actions.
   • Alternatively, you can build it yourself by cloning the repo and running ./build.sh. Building requires Go 1.21 or higher.
   • bbctl supports amd64 and arm64 on Linux and macOS. Windows is not supported natively, please use WSL.
2. Log into your Beeper account with bbctl login.

Then continue with one of the sections below, depending on whether you want to run an official Beeper bridge or a 3rd party bridge.

Official bridges

For Python bridges, you must install Python 3 with the venv module with your OS package manager. For example, sudo apt install python3 python3-venv on Debian-based distros. The Python version built into macOS may be new enough, or you can get the latest version via brew. The minimum Python version varies by bridge, but if you use the latest Debian or Ubuntu LTS, it should be new enough.

Some bridges require ffmpeg for converting media (e.g. when sending gifs), so you should also install that with your OS package manager (sudo apt install ffmpeg on Debian or brew install ffmpeg on macOS).

After installing relevant dependencies:

3. Run bbctl run <name> to run the bridge.
   • <name> should start with sh- and consist of a-z, 0-9 and -.
   • If <name> contains the bridge type, it will be automatically detected. Otherwise pass the type with --type <type>.
   • See the table below for supported official bridges.
   • The bridge will be installed to ~/.local/share/bbctl. You can change the directory in the config file at ~/.config/bbctl.json.
4. For now, you'll have to configure the bridge by sending a DM to the bridge bot (@<name>bot:beeper.local). Configuring self-hosted bridges through the chat networks dialog will be available in the future. Spaces and starting chats are also not yet available, although you can start chats using the pm command with the bridge bot.

There is currently a bug in Beeper Desktop that causes it to create encrypted DMs even if the recipient doesn't support it. This means that for non-e2ee- capable bridges like Heisenbridge, you'll have to create the DM with the bridge bot in another Matrix client, or using the create group chat button in Beeper Desktop.

Currently the bridge will run in foreground, so you'll have to keep bbctl run active somewhere (tmux is a good option). In the future, a service mode will be added where the bridge is registered as a systemd or launchd service to be started automatically by the OS.

Official bridge list

When using bbctl run or bbctl config and the provided <name> contains one of the identifiers (second column) listed below, bbctl will automatically guess that type. A substring match is sufficient, e.g. sh-mywhatsappbridge will match whatsapp. The first listed identifier is the "primary" one that can be used with the --type flag.

Bridge	Identifier
mautrix-telegram	telegram
mautrix-whatsapp	whatsapp
mautrix-signal	signal
mautrix-discord	discord
mautrix-slack	slack
mautrix-gmessages	gmessages, googlemessages, rcs, sms
mautrix-meta	meta, instagram, facebook
mautrix-googlechat	googlechat, gchat
mautrix-twitter	twitter
mautrix-imessage	imessage
beeper-imessage	imessagego
linkedin-matrix	linkedin
heisenbridge	heisenbridge, irc

3rd party bridges

3. Run bbctl register <name> to generate an appservice registration file.
   • <name> is a short name for the bridge (a-z, 0-9, -). The name should start with sh-. The bridge user ID namespace will be @<name>_.+:beeper.local and the bridge bot will be @<name>bot:beeper.local.
   • Optionally you can pass -a <address> to have the Beeper server push events directly to the bridge. However, this requires that the bridge is publicly accessible. The proxy option below is easier.
4. Now you can configure and run the bridge by following the bridge's own documentation.
5. If you didn't pass an address to register, modify the registration file to point at where the bridge will listen locally (e.g. url: http://localhost:8080), then run bbctl proxy -r registration.yaml to start the proxy.
   • The proxy will connect to the Beeper server using a websocket and push received events to the bridge via HTTP. Since the HTTP requests are all on localhost, you don't need port forwarding or TLS certificates.

Note that the homeserver URL may change if you're moved to a different cluster. In general, that shouldn't happen, but it's not impossible.

If you want to get the registration again later, you can add the --get flag. Just re-running register is allowed too, but you need to provide the address again if you do that (which also means if you want to change the address, just re-run register with the new address).

You can use --json with register to get the whole response as JSON instead of registration YAML and pretty-printed extra details. This may be useful if you want to automate fetching the homeserver URL.

Deleting bridges

If you don't want a self-hosted bridge anymore, you can delete it using bbctl delete <name>. Deleting a bridge will permanently erase all traces of it from the Beeper servers (e.g. any rooms and ghost users it created). For official bridges, it will also delete the local data directory with the bridge config, database and python virtualenv (if applicable).

bridge-manager's Issues

Respond with proper error message if email doesn't have a Beeper account

root@v37905:/home# bbctl login
? Email: [email protected]
? Enter login code sent to your email: CODE
failed to log in: failed to POST /_matrix/client/v3/login: M_FORBIDDEN (HTTP 403): Token field for JWT is missing

Signal bridge crashes

I appear to get ~daily Signal bridge crashes with the following:

2023-11-12T01:37:27-05:00 DBG Got message from signal chat_id=36af6b3d-196b-4346-85bc-14eb9c3160aa
2023-11-12T01:37:27-05:00 WRN Trying to get puppet with empty signal_user_id
2023-11-12T01:37:27-05:00 DBG Outgoing message: receiptMessage (message), { type (enum), timestamp (uint64), [ <>, ] }  component=signalmeow
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x80 pc=0xbe084a]

goroutine 1556 [running]:
main.(*Portal).addMentionsToMatrixBody(0xc000c29790, 0xc00033b8c0, {0xc00153c960, 0x1, 0x0?})
        /builds/mautrix/signalgo/portal.go:976 +0xea
main.(*Portal).handleSignalTextMessage(0xc000c29790, {{0x158e7f0, 0xc0014dd340}, 0xc0004180b0, 0xc0008abc30, 0x0}, 0x0?)
        /builds/mautrix/signalgo/portal.go:1080 +0x1c5
main.(*Portal).handleSignalMessages(0xc000c29790, {{0x158e7f0, 0xc0014dd340}, 0xc0004180b0, 0xc0008abc30, 0x0})
        /builds/mautrix/signalgo/portal.go:856 +0x234
main.(*Portal).messageLoop(0xc000c29790)
        /builds/mautrix/signalgo/portal.go:237 +0x175
created by main.(*SignalBridge).NewPortal in goroutine 124
        /builds/mautrix/signalgo/portal.go:223 +0x413
Bridge exited

I'm just going to put it in a while loop for now; I'd file this against upstream, but I have no idea what version this is, so I'm putting this here.

Unsupported bridge type for bbctl run for signalgo

Per #8 I'd like to request a bbctl run sh-signal to run signalgo.

failed to get whoami: unexpected status code 401

Unable to login with 0.3.0:

$ bbctl-0.3 login
failed to get whoami: unexpected status code 401

but works as expected with 0.2.0:

$ bbctl-0.2 login
? Username:

Tested on macOS 13.4 and 13.4.1, both arm64 and amd64 versions of both 0.2 and 0.3

Failed to send transaction request error

Hey all, not sure if this is related to mautrix-meta or bbctl but I am posting this here.

I run the sh-instagram bridge but wanted to change profile pictures to show correctly on iOS. after having some trouble here is what i did

1. Fully deleted the directory locally
2. Deleted the bridge from bbctl
3. created a new bridge
4. without making changes to the config at all, did bbctl run --no-override-config sh-instagram, but get the error
5. tried bbctl run sh-instagram and do not get the error at all

Unfortunately i'm still getting this error. I listed the full errors below, this is what occurs when I run it (sometimes the errors only start when I start typing anything to the instagram bridge bot) and will repeat untii ctrl+c which is why it stops. Thank you for any help, I do greatly appreciate it

May 29 18:07:40.878 INF Forwarding transaction contents={"edu":1,"pdu":0} req_id=1 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:40.878 ERR Failed to send transaction request error="Put \"websocket/_matrix/app/v1/transactions/e264284_d23743_r126574_t74030-%3Ee264284_d23743_r126574_t74031\": unsupported protocol scheme \"\"" req_id=1 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:40.878 DBG Sent response to transaction req_id=1 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:40.982 INF Forwarding transaction contents={"edu":1,"pdu":0} req_id=2 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:40.983 ERR Failed to send transaction request error="Put \"websocket/_matrix/app/v1/transactions/e264284_d23743_r126574_t74030-%3Ee264284_d23743_r126574_t74031\": unsupported protocol scheme \"\"" req_id=2 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:40.983 DBG Sent response to transaction req_id=2 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:42.085 INF Forwarding transaction contents={"edu":1,"pdu":0} req_id=3 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:42.085 ERR Failed to send transaction request error="Put \"websocket/_matrix/app/v1/transactions/e264284_d23743_r126574_t74030-%3Ee264284_d23743_r126574_t74031\": unsupported protocol scheme \"\"" req_id=3 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:42.085 DBG Sent response to transaction req_id=3 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:43.188 INF Forwarding transaction contents={"edu":1,"pdu":0} req_id=4 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:43.188 ERR Failed to send transaction request error="Put \"websocket/_matrix/app/v1/transactions/e264284_d23743_r126574_t74030-%3Ee264284_d23743_r126574_t74031\": unsupported protocol scheme \"\"" req_id=4 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:43.188 DBG Sent response to transaction req_id=4 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:44.292 INF Forwarding transaction contents={"edu":1,"pdu":0} req_id=5 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:44.292 ERR Failed to send transaction request error="Put \"websocket/_matrix/app/v1/transactions/e264284_d23743_r126574_t74030-%3Ee264284_d23743_r126574_t74031\": unsupported protocol scheme \"\"" req_id=5 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:44.292 DBG Sent response to transaction req_id=5 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:45.395 INF Forwarding transaction contents={"edu":1,"pdu":0} req_id=6 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:45.396 ERR Failed to send transaction request error="Put \"websocket/_matrix/app/v1/transactions/e264284_d23743_r126574_t74030-%3Ee264284_d23743_r126574_t74031\": unsupported protocol scheme \"\"" req_id=6 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction May 29 18:07:45.396 DBG Sent response to transaction req_id=6 transaction_id=e264284_d23743_r126574_t74030->e264284_d23743_r126574_t74031 ws_command=transaction

feature request: source for beeper client

just wondering, its awesome to have the bridges to be open sourced for self hosting purposes,

but what about the beeper client? i might not have searched properly but i don't see a source for it. is there a reason why?

Feature Request: Homebrew Cask?

Currently the setup process for bbctl involves downloading the binary and, I guess... manually moving it to the correct folder in one's $PATH? It would be a lot more straightforward if bbctl were distributed through Homebrew, which supports both Linux and macOS and, among other things, takes care of deciding where to put binaries and semi-automatically updating packages to newly available versions.

Creating a Homebrew "Cask" (install formula) seems to be a relatively straightforward process, but it's just enough beyond my personal experience level that I would rather start by nudging you folx to create one yourselves. Hypothetically I could also ask in the Homebrew GitHub Discussions, but the way the forum is set up makes this less than straightforward, so I'm asking here, first.

Unable to use official bridges: wrong as_token

bbctl version v0.4.0+dev.7d5d7bad (built at Jul 9 2023, 21:48:56 CEST)
go version go1.19.9 linux/amd64

./bbctl config sh-discord

and/or

./bbctl config sh-gmessages

{"level":"info","name":"mautrix-discord","version":"0.5.0","built_at":"Jun 16 2023, 11:52:36","go_version":"go1.20.4","time":"2023-07-09T22:15:55.401670576+02:00","message":"Initializing bridge"}
{"level":"debug","time":"2023-07-09T22:15:55.401777858+02:00","message":"Initializing database connection"}
{"level":"debug","time":"2023-07-09T22:15:55.402437616+02:00","message":"Initializing state store"}
{"level":"debug","time":"2023-07-09T22:15:55.403596602+02:00","message":"Initializing Matrix event processor"}
{"level":"debug","time":"2023-07-09T22:15:55.403640648+02:00","message":"Initializing Matrix event handler"}
{"level":"info","time":"2023-07-09T22:15:55.403714518+02:00","message":"Bridge initialization complete, starting..."}
{"level":"debug","time":"2023-07-09T22:15:55.403739051+02:00","message":"Running database upgrades"}
{"level":"info","db_section":"main","current_version":23,"oldest_compatible_version":19,"latest_known_version":22,"time":"2023-07-09T22:15:55.409408906+02:00","message":"Database is up to date"}
{"level":"info","db_section":"matrix_state","current_version":5,"oldest_compatible_version":5,"latest_known_version":5,"time":"2023-07-09T22:15:55.411260755+02:00","message":"Database is up to date"}
{"level":"debug","time":"2023-07-09T22:15:55.411299595+02:00","message":"Starting application service websocket"}
{"level":"debug","time":"2023-07-09T22:15:55.411328871+02:00","message":"Checking connection to homeserver"}
{"level":"debug","as_user_id":"@sh-discordbot:beeper.local","req_id":1,"method":"GET","url":"https://lb.nodes.6187fa.bridges.beeper.com/jakub/_matrix/client/versions?user_id=%40sh-discordbot%3Abeeper.local","time":"2023-07-09T22:15:55.411384062+02:00","message":"Sending request"}
{"level":"error","action":"appservice websocket","error":"websocket request returned M_UNKNOWN_TOKEN (HTTP 401): Unrecognized access token","time":"2023-07-09T22:15:55.738673167+02:00","message":"Error in appservice websocket"}
{"level":"info","action":"appservice websocket","backoff_seconds":4,"time":"2023-07-09T22:15:55.738751382+02:00","message":"Websocket disconnected, reconnecting..."}
{"level":"debug","as_user_id":"@sh-discordbot:beeper.local","req_id":1,"method":"GET","path":"/versions","status_code":200,"response_length":279,"response_mime":"application/json","duration":331.574609,"beeper_request_id":"cilhauvg4jirv8m983s0","time":"2023-07-09T22:15:55.743153211+02:00","message":"Request completed"}
{"level":"debug","as_user_id":"@sh-discordbot:beeper.local","req_id":2,"method":"GET","url":"https://lb.nodes.6187fa.bridges.beeper.com/jakub/_matrix/client/v3/account/whoami?user_id=%40sh-discordbot%3Abeeper.local","time":"2023-07-09T22:15:55.745107146+02:00","message":"Sending request"}
{"level":"debug","as_user_id":"@sh-discordbot:beeper.local","req_id":2,"method":"GET","path":"/v3/account/whoami","status_code":401,"response_length":66,"response_mime":"application/json","duration":69.75632,"beeper_request_id":"cilhauvg4jirv8m983sg","time":"2023-07-09T22:15:55.815017552+02:00","message":"Request completed"}
{"level":"fatal","time":"2023-07-09T22:15:55.815209065+02:00","message":"The as_token was not accepted. Is the registration file installed in your homeserver correctly?"}

ARM64 Docker support

Currently when trying to run the docker container on a Raspberry Pi it fails to start with:

exec /bin/sh: exec format error

It would be nice to be able to run the bridge manager through docker on arm64

Add deamon mode for self-hosted bridges

Hello,
will it be possible to run the self-hosted bridges (via run command) as a deamon in the background in the future?
When exiting the bbctl utility the self hosted bridge will be stopped.
Additionally, please add the possibility to run multiple bridges in the background.
Thank you!

Required specs for running a single user with all the bridges?

I could not find this information: how much RAM/what CPU do I need to run an instance of all the bridges with a single user?

Thank you !

Any plans for including bridges to the fediverse (Mastodon, Friendica)?

Having Beeper saves me several pinned tabs in a separate browser window for all my chat apps (each tab asking for a load of memory as well), but I still have a Friendica and a Mastodon account in tabs. Is a birdge to the fediverse in the plans?

Thanks!

How to connect the Android app to it?

I want to try to the project but how can I connection my phone to it?

On my app, I only the following limited list of servers:

• beeper.com
• beeper-staging.com
• beeper-dev.com

So, I have the server but I don't have a way to connect to it.

Can I use bridge-manager with synapse matrix server?

Add an official e-mail bridge.

https://github.com/beeper/bridge-manager/tree/063928568d5d9c0c2c7ae072570f3878a159dddd?tab=readme-ov-file#official-bridge-list doesn't list one despite e-mail being the most used federated communication platform in the world, and Matrix officially recognizing https://matrix.org/ecosystem/bridges/email/.

Native Windows Support

Are there any plans for native Windows support? This is a missed opportunity, and I would love to know why this hasn't been done.

bbctl not checking if artifact exists for correct architecture

The latest commit of mautrix discord 2138b611 doesn't have a build artifact for darwin amd64.

However bbctl still recognises the new commit and tries to download the binary for a missing building artifact and instead downloads the html source of the mau.dev login page.

Thus when trying to run bbctl run sh-discord you get a exec format error as it's not a binary.

Downloading older build artifacts for the correct arch doesn't work either as bbctl still tries to update them.

Maybe add support for Snapchat in the future ?

Hello, I would really like to have support for Snapchat (messages only !). I know adding support to a message system is pretty hard to make and maintain, but there is absolutely no problem if it's not now !
Thanks, and GG for this huge project !