{"id":18140548,"url":"https://github.com/beeper/bridge-manager","last_synced_at":"2026-02-24T19:02:29.776Z","repository":{"id":65742644,"uuid":"593668856","full_name":"beeper/bridge-manager","owner":"beeper","description":"A tool for running self-hosted bridges with the Beeper Matrix server.","archived":false,"fork":false,"pushed_at":"2025-03-01T12:12:01.000Z","size":362,"stargazers_count":878,"open_issues_count":14,"forks_count":53,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-03-01T12:28:24.320Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beeper.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-26T15:18:51.000Z","updated_at":"2025-03-01T12:12:04.000Z","dependencies_parsed_at":"2023-09-22T06:49:47.807Z","dependency_job_id":"3c54914d-15ab-4df3-9c9b-7ff824080123","html_url":"https://github.com/beeper/bridge-manager","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fbridge-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fbridge-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fbridge-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fbridge-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beeper","download_url":"https://codeload.github.com/beeper/bridge-manager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246399816,"owners_count":20770907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-01T16:02:03.112Z","updated_at":"2026-02-24T19:02:29.770Z","avatar_url":"https://github.com/beeper.png","language":"Go","funding_links":[],"categories":["Install from Source","Go","Official Resources"],"sub_categories":["iMessage","Official Repositories"],"readme":"# Beeper Bridge Manager\nA tool for running self-hosted bridges with the Beeper Matrix server.\n\nThe primary use case is running custom/3rd-party bridges with Beeper. You can\nconnect any\u003csup\u003e†\u003c/sup\u003e spec-compliant Matrix application service to your Beeper\naccount without having to self-host a whole Matrix homeserver. Note that if you\nrun 3rd party bridges that don't support end-to-bridge encryption, message\ncontents will be visible to Beeper servers.\n\n\u003csub\u003e†caveat: hungryserv does not implement the entire Matrix client-server API, so\nit's possible some bridges won't work - you can report such cases in the\nself-hosting support room linked below or in GitHub issues here\u003c/sub\u003e\n\nYou can also self-host the official bridges for maximum security using this\ntool (so that message re-encryption happens on a machine you control rather\nthan on Beeper servers).\n\nThis tool can not be used with any other Matrix homeserver, like self-hosted\nSynapse instances. It is only for connecting self-hosted bridges to the\nbeeper.com server. For self-hosting the entire stack, refer to the official\ndocumentation of the various projects\n([Synapse](https://element-hq.github.io/synapse/latest/),\n[mautrix bridges](https://docs.mau.fi/bridges/)).\n\n\u003e [!NOTE]\n\u003e Self-hosted bridges are not entitled to the usual level of customer support\n\u003e on Beeper. If you need help with self-hosting bridges using this tool, please\n\u003e join [#self-hosting:beeper.com] instead of asking in your support room.\n\n[#self-hosting:beeper.com]: https://matrix.to/#/#self-hosting:beeper.com\n\n## Usage\n1. Download the latest binary from [GitHub releases](https://github.com/beeper/bridge-manager/releases)\n   or [actions](https://nightly.link/beeper/bridge-manager/workflows/go.yaml/main).\n   * Alternatively, you can build it yourself by cloning the repo and running\n     `./build.sh`. Building requires Go 1.23 or higher.\n   * bbctl supports amd64 and arm64 on Linux and macOS.\n     Windows is not supported natively, please use WSL.\n2. Log into your Beeper account with `bbctl login`.\n\nThen continue with one of the sections below, depending on whether you want to\nrun an official Beeper bridge or a 3rd party bridge.\n\n### Official bridges\nFor Python bridges, you must install Python 3 with the `venv` module with your\nOS package manager. For example, `sudo apt install python3 python3-venv` on\nDebian-based distros. The Python version built into macOS may be new enough, or\nyou can get the latest version via brew. The minimum Python version varies by\nbridge, but if you use the latest Debian or Ubuntu LTS, it should be new enough.\n\nSome bridges require ffmpeg for converting media (e.g. when sending gifs), so\nyou should also install that with your OS package manager (`sudo apt install ffmpeg`\non Debian or `brew install ffmpeg` on macOS).\n\nAfter installing relevant dependencies:\n\n3. Run `bbctl run \u003cname\u003e` to run the bridge.\n   * `\u003cname\u003e`  should start with `sh-` and consist of a-z, 0-9 and -.\n   * If `\u003cname\u003e` contains the bridge type, it will be automatically detected.\n     Otherwise pass the type with `--type \u003ctype\u003e`.\n   * See the table below for supported official bridges.\n   * The bridge will be installed to `~/.local/share/bbctl`. You can change the\n     directory in the config file at `~/.config/bbctl.json`.\n4. For now, you'll have to configure the bridge by sending a DM to the bridge\n   bot (`@\u003cname\u003ebot:beeper.local`). Configuring self-hosted bridges through the\n   chat networks dialog will be available in the future. Spaces and starting\n   chats are also not yet available, although you can start chats using the\n   `pm` command with the bridge bot.\n\nThere is currently a bug in Beeper Desktop that causes it to create encrypted\nDMs even if the recipient doesn't support it. This means that for non-e2ee-\ncapable bridges like Heisenbridge, you'll have to create the DM with the bridge\nbot in another Matrix client, or using the create group chat button in Beeper\nDesktop.\n\nCurrently the bridge will run in foreground, so you'll have to keep `bbctl run`\nactive somewhere (tmux is a good option). In the future, a service mode will be\nadded where the bridge is registered as a systemd or launchd service to be\nstarted automatically by the OS.\n\n#### Official bridge list\nWhen using `bbctl run` or `bbctl config` and the provided `\u003cname\u003e` contains one\nof the identifiers (second column) listed below, bbctl will automatically guess\nthat type. A substring match is sufficient, e.g. `sh-mywhatsappbridge` will\nmatch `whatsapp`. The first listed identifier is the \"primary\" one that can be\nused with the `--type` flag.\n\n| Bridge               | Identifier                           |\n|----------------------|--------------------------------------|\n| [mautrix-telegram]   | telegram                             |\n| [mautrix-whatsapp]   | whatsapp                             |\n| [mautrix-signal]     | signal                               |\n| [mautrix-discord]    | discord                              |\n| [mautrix-slack]      | slack                                |\n| [mautrix-gmessages]  | gmessages,  googlemessages, rcs, sms |\n| [mautrix-gvoice]     | gvoice, googlevoice                  |\n| [mautrix-meta]       | meta, instagram, facebook            |\n| [mautrix-googlechat] | googlechat, gchat                    |\n| [mautrix-twitter]    | twitter                              |\n| [mautrix-bluesky]    | bluesky, bsky                        |\n| [mautrix-imessage]   | imessage                             |\n| [beeper-imessage]    | imessagego                           |\n| [mautrix-linkedin]   | linkedin                             |\n| [heisenbridge]       | heisenbridge, irc                    |\n\n[mautrix-telegram]: https://github.com/mautrix/telegram\n[mautrix-whatsapp]: https://github.com/mautrix/whatsapp\n[mautrix-signal]: https://github.com/mautrix/signal\n[mautrix-discord]: https://github.com/mautrix/discord\n[mautrix-slack]: https://github.com/mautrix/slack\n[mautrix-gmessages]: https://github.com/mautrix/gmessages\n[mautrix-gvoice]: https://github.com/mautrix/gvoice\n[mautrix-meta]: https://github.com/mautrix/meta\n[mautrix-googlechat]: https://github.com/mautrix/googlechat\n[mautrix-twitter]: https://github.com/mautrix/twitter\n[mautrix-bluesky]: https://github.com/mautrix/bluesky\n[mautrix-imessage]: https://github.com/mautrix/imessage\n[beeper-imessage]: https://github.com/beeper/imessage\n[mautrix-linkedin]: https://github.com/mautrix/linkedin\n[heisenbridge]: https://github.com/hifi/heisenbridge\n\n### 3rd party bridgev2-based bridges\nIf you have a 3rd party bridge that's built on top of mautrix-go's bridgev2\nframework, you can have bbctl generate a mostly-complete config file:\n\n3. Run `bbctl config --type bridgev2 \u003cname\u003e` to generate a bridgev2 config with\n   everything except the `network` section.\n   * `\u003cname\u003e` is a short name for the bridge (a-z, 0-9, -). The name should\n     start with `sh-`. The bridge user ID namespace will be `@\u003cname\u003e_.+:beeper.local`\n     and the bridge bot will be `@\u003cname\u003ebot:beeper.local`.\n4. Add the `network` section containing the bridge-specific configuration if\n   necessary, then run the bridge normally.\n\nAll bridgev2 bridges support appservice websockets, so using `bbctl proxy` is\nnot necessary.\n\n### 3rd party custom bridges\nFor any 3rd party bridges that don't use bridgev2, you'll only get a registration\nfile from bbctl and will have to configure the bridge yourself. Also, since such\n3rd party bridges are unlikely to support Beeper's appservice websocket protocol,\nyou probably have to use `bbctl proxy` to connect to the websocket and turn\nincoming data into HTTP requests for the bridge.\n\n3. Run `bbctl register \u003cname\u003e` to generate an appservice registration file.\n   * `\u003cname\u003e` is the same as in the above section.\n4. Now you can configure and run the bridge by following the bridge's own\n   documentation.\n5. Modify the registration file to point at where the bridge will listen locally\n   (e.g. `url: http://localhost:8080`), then run `bbctl proxy -r registration.yaml`\n   to start the proxy.\n   * The proxy will connect to the Beeper server using a websocket and push\n     received events to the bridge via HTTP. Since the HTTP requests are all on\n     localhost, you don't need port forwarding or TLS certificates.\n\nNote that the homeserver URL is not guaranteed to be stable forever, it has\nchanged in the past, and it may change again in the future.\n\nYou can use `--json` with `register` to get the whole response as JSON instead\nof registration YAML and pretty-printed extra details. This may be useful if\nyou want to automate fetching the homeserver URL.\n\n### Deleting bridges\nIf you don't want a self-hosted bridge anymore, you can delete it using\n`bbctl delete \u003cname\u003e`. Deleting a bridge will permanently erase all traces of\nit from the Beeper servers (e.g. any rooms and ghost users it created).\nFor official bridges, it will also delete the local data directory with the\nbridge config, database and python virtualenv (if applicable).\n\nNote that deleting a bridge through the Beeper client settings will\n*not* delete the bridge database that is stored locally; you must\ndelete that yourself, or use `bbctl delete` instead. (If you created\nthe bridge database with `bbctl run -l`, then run `bbctl delete -l`\nfrom the same working directory to delete it.)\n\nIf you later re-add a self-hosted bridge after deleting it from the\nBeeper servers but not deleting the local database, you should expect\nerrors, as the bridge will have been removed from Matrix rooms that it\nthinks it is a member of.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeeper%2Fbridge-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeeper%2Fbridge-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeeper%2Fbridge-manager/lists"}