# Beeper Bridge Manager for Self-Hosted Bridges > Beeper Bridge Manager is a Go CLI for running official or third-party bridges against the Beeper Matrix server. It fits users who want local bridge execution, but it cannot operate with another homeserver such as Synapse. **beeper/bridge-manager** — A tool for running self-hosted bridges with the Beeper Matrix server. - Repository: https://github.com/beeper/bridge-manager - Stars: 1,426 · Forks: 94 - Language: Go - License: Apache-2.0 - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/beeper-bridge-manager ## What bbctl connects to Beeper Beeper Bridge Manager, or bbctl, solves a specific hosting problem: connecting a Matrix application-service bridge to a Beeper account without running a separate Matrix homeserver. The intended users are Beeper users who want to self-host an official bridge or connect a third-party bridge built around a supported Matrix application-service model. The project has a narrower scope than a general Matrix homeserver manager. The README states that it cannot be used with another homeserver, including a self-hosted Synapse instance. Its target is the beeper.com server. That boundary matters for adoption. An operator who wants to control the homeserver, register application services, and manage the wider Matrix deployment should use the relevant Synapse or mautrix documentation instead. There is also a security distinction between bridge ownership and message visibility. The README says that self-hosting official bridges can make message re-encryption happen on a machine controlled by the operator rather than on Beeper servers. For third-party bridges that do not support end-to-bridge encryption, however, message contents will be visible to Beeper servers. bbctl does not remove that limitation. The security decision therefore belongs partly to the bridge, not only to bbctl. ## How bbctl launches and identifies bridges The CLI uses a command structure that separates account access from bridge execution. The operator authenticates with `bbctl login`, then starts either an official bridge or a third-party bridge with a command that includes a name. Official bridge names must begin with `sh-` and may contain lowercase letters, numbers, and hyphens. bbctl detects the bridge type when the selected name contains a recognized identifier. The README says that `sh-mywhatsappbridge` is sufficient to match the `whatsapp` type. If the name does not contain the type, the operator can pass `--type`. The supported official list includes mautrix bridges for Telegram, WhatsApp, Signal, Discord, Slack, Google Messages, Google Voice, Meta, Google Chat, Twitter, Bluesky, iMessage, and LinkedIn, plus Beeper's iMessage bridge and Heisenbridge. Matching is described as a substring operation, so naming can influence which bridge is selected. Official bridge files are installed under `~/.local/share/bbctl`, while the installation directory can be changed through `~/.config/bbctl.json`. The documented `run` command starts the bridge in the foreground. There is no service mode in the documented workflow yet, so the process must remain attached to the terminal or be kept in another session such as tmux. That is a meaningful deployment constraint for anyone expecting unattended operation. ## Installing bbctl and starting a bridge The README gives three installation paths. Homebrew is the documented package-manager path, release binaries are available from GitHub releases, and source builds use the repository's build script. Building from source requires Go 1.25 or higher. The repository's `go.mod` declares Go 1.25.0 and a `toolchain` directive for Go 1.26.5. Install bbctl with Homebrew: ```bash brew install beeper/tap/bbctl ``` This installs the `bbctl` executable through the `beeper/tap` Homebrew tap. The README states that bbctl supports amd64 and arm64 on Linux and macOS. Native Windows installation is not supported, and the documented workaround is WSL. Authenticate against the Beeper account before running a bridge: ```bash bbctl login ``` After authentication, the first official-bridge operation is normally `bbctl run `. The exact name must begin with `sh-`. Depending on the selected bridge, Python 3 with the `venv` module or ffmpeg may also be required. The README gives Debian and macOS examples, but the required version varies by bridge. The README also documents automatic detection through a name containing the bridge type: ```bash ``` The README uses `sh-mywhatsappbridge` to illustrate matching the `whatsapp` bridge identifier. If automatic detection is not sufficient, it documents the `--type ` form: ```bash bbctl run --type ``` The placeholder `` is documented as the type selector, but the README excerpt does not give a complete concrete invocation using it. The bridge must then be configured by sending a direct message to `@bot:beeper.local`. The README notes that configuration through the chat networks dialog is planned for the future, while chats can still be started with the `pm` command. ## Third-party bridgev2 configuration and runtime limits For third-party bridges built on mautrix-go's bridgev2 framework, the documented workflow uses `bbctl config` to generate a mostly complete configuration file. The README states that the generated file contains everything except the `network` section. This makes bbctl a starting point for bridge configuration rather than a fully automatic integration for every third-party bridge. The command is documented as follows: ```bash bbctl config --type bridgev2 ``` The bridge name follows the documented constraints of beginning with `sh-` and using lowercase letters, numbers, or hyphens. The remaining configuration still needs to be supplied by the operator. The README excerpt does not document a complete third-party configuration example, so the exact network settings, bridge-specific environment variables, or startup behavior cannot be confirmed from it. The documented bridge runtime has several practical constraints. Some bridges require Python and ffmpeg, while others may have different minimum Python versions. A bridge that does not implement the complete Matrix client-server API may fail against hungryserv, which the README identifies as the server-side compatibility caveat. The README also documents a Beeper Desktop bug that can create encrypted direct messages even when the recipient does not support encryption. For non-e2ee-capable bridges such as Heisenbridge, it says to create the direct message in another Matrix client or use Beeper Desktop's create group chat button. These are operational edge cases that should be checked before selecting a bridge. ## Platforms, encryption, and maintenance signals The project is a Go CLI with dependencies including mautrix, zerolog, urfave/cli, and Go's standard cryptographic packages. Its documented distribution target is limited: amd64 and arm64 on Linux and macOS. Windows is not supported natively, so WSL is required. That makes platform selection a deployment requirement rather than an incidental detail. The repository is licensed under Apache-2.0. The license permits use and modification under its terms, but this article does not interpret the license or provide legal guidance. Operators should review the LICENSE file for the applicable obligations. The repository is not archived. Its last push was on 2026-10-02. The listed releases include v0.15.0 on 2026-07-16, v0.14.0 on 2026-02-24, and v0.13.0 on 2024-12-15. Those dates provide release history, but the README does not document a formal upgrade procedure, rollback procedure, service-manager integration, or compatibility policy for bridge versions. A source build also inherits the Go and dependency requirements shown in `go.mod`. Upgrade planning therefore requires checking the selected bridge's own documentation as well as bbctl's release history. ## bbctl versus a standalone Matrix stack The real alternative is to run the complete Matrix stack yourself, using a homeserver such as Synapse and the relevant bridge documentation. That approach changes the ownership boundary. Instead of connecting a self-hosted bridge to the Beeper server through bbctl, the operator controls the homeserver and handles application-service registration and deployment through that stack. bbctl is the narrower option for users who already want a Beeper account and want to move bridge execution, or parts of it, onto a machine they control. The README specifically positions official self-hosted bridges as a way to perform message re-encryption on the operator's machine. The alternative does not inherit that Beeper-specific setup because it is a different deployment model. The trade-off is operational control. bbctl reduces the need to run a separate homeserver, but it keeps the product tied to beeper.com, leaves bridge configuration partly manual, and currently runs the bridge in the foreground. A standalone stack offers broader homeserver control, but requires the operator to assemble and operate the homeserver and bridge environment. Neither choice automatically solves third-party bridges that lack end-to-bridge encryption. ## Conclusion Adopt Beeper Bridge Manager if you want to run an official or bridgev2-based third-party bridge with a Beeper account and accept foreground operation and Beeper-specific constraints. Do not choose it for a standalone Synapse homeserver. Verify the bridge type, runtime dependencies, encryption support, and target platform before deployment, especially because native Windows support is absent. ## FAQ ### Can Beeper Bridge Manager run with Synapse? No. The README says the tool is only for connecting self-hosted bridges to the beeper.com server and cannot be used with another Matrix homeserver such as self-hosted Synapse. ### How do I install bbctl? The README documents `brew install beeper/tap/bbctl` for Homebrew, release binaries from GitHub releases, or building the repository with `./build.sh`. Building from source requires Go 1.25 or higher. ### Does bbctl support Windows? Native Windows support is not provided. The README says Windows users should use WSL, while native binaries are documented for amd64 and arm64 on Linux and macOS. ### How are third-party bridgev2 configurations created? The documented command is `bbctl config --type bridgev2 `. It generates a mostly complete configuration with everything except the `network` section, which still needs to be configured. ## Sources - [beeper/bridge-manager on GitHub](https://github.com/beeper/bridge-manager) - [Issues](https://github.com/beeper/bridge-manager/issues) - [License: Apache-2.0](https://github.com/beeper/bridge-manager/blob/main/LICENSE) - [README](https://github.com/beeper/bridge-manager/blob/main/README.md) - [Releases](https://github.com/beeper/bridge-manager/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/beeper-bridge-manager