Self-Hosting Bridges

Support Notice

Self-hosting bridges are not entitled to the usual level of customer support.

For help with self-hosting, join #self-hosting:beeper.com.

Overview

The easiest way to self-host bridges is using Beeper Bridge Manager (bbctl). It’s a tool for running self-hosted bridges with your Beeper account.

Key Benefits

• Security - Run official Beeper bridges on your own hardware securely
• Flexibility - Connect custom or third-party bridges without self-hosting a full Matrix server
• Control - Maintain complete control over message processing and encryption

Tip

Accounts bridged with self-hosting are free and do not count against your account limits.

Prerequisites

Before you begin, ensure you have:

• Operating System: Linux or macOS (amd64 or arm64)

  Note

  Windows users should use WSL
• Python: Python 3 with venv module for Python-based bridges
• ffmpeg: Required for media conversion in some bridges
• Beeper account: You’ll need an active Beeper account

Installation

Step 1: Download bbctl

GitHub releases

Download the appropriate binary for your system:

Linux (x86_64)

Linux (arm64)

macOS (Intel)

macOS (Apple Silicon)

You can check the GitHub releases for the latest version, checksum(s) and source code.

Build from source

git clone https://github.com/beeper/bridge-manager.git
cd bridge-manager
./build.sh

Step 2: Install Dependencies

Debian/Ubuntu

sudo apt install python3 python3-venv ffmpeg

macOS

brew install python ffmpeg

Step 3: Login to Beeper

bbctl login

Running Official Bridges

1. Start a bridge

   bbctl run sh-<bridgename>

   Example: bbctl run sh-whatsapp

2. Configure the bridge

   • Send a DM to the bridge bot: @sh-<bridgename>bot:beeper.local
   • Follow the bot’s instructions to log in to the remote network

3. Keep it running

   • Currently runs in foreground (use tmux or screen for persistence)
   • Service mode for automatic startup coming soon

Data Storage

Bridge data is stored in ~/.local/share/bbctl by default.

You can change this location in ~/.config/bbctl.json.

Supported Official Bridges

Bridge	Identifier(s)	Repository
Telegram	telegram	mautrix/telegram
WhatsApp	whatsapp	mautrix/whatsapp
Signal	signal	mautrix/signal
Discord	discord	mautrix/discord
Slack	slack	mautrix/slack
Google Messages	gmessages, googlemessages, rcs, sms	mautrix/gmessages
Google Voice	gvoice, googlevoice	mautrix/gvoice
Meta (FB/Instagram)	meta, instagram, facebook	mautrix/meta
Google Chat	googlechat, gchat	mautrix/googlechat
Twitter	twitter	mautrix/twitter
Bluesky	bluesky, bsky	mautrix/bluesky
iMessage	imessage	mautrix/imessage
iMessage (Go)	imessagego	beeper/imessage
LinkedIn	linkedin	mautrix/linkedin
IRC (Heisenbridge)	heisenbridge, irc	hifi/heisenbridge

Running Third-Party Bridges

BridgeV2-based Bridges

For bridges built with mautrix-go’s bridgev2 framework:

1. Generate config

   bbctl config --type bridgev2 sh-<bridgename>

2. Add network configuration

   Add the network section to the generated config with bridge-specific settings

3. Run the bridge

   Run the bridge with your config file

Custom Bridges

For other third-party bridges:

1. Generate registration

   bbctl register sh-<bridgename>

2. Configure the bridge

   Configure the bridge according to its documentation

3. Run the proxy

   bbctl proxy -r registration.yaml

   This connects your bridge to Beeper

Managing Bridges

Delete a Bridge

Caution

This action is permanent and cannot be undone.

bbctl delete sh-<bridgename>

This permanently removes the bridge and all associated data from Beeper servers.