---
title: Self-Hosting Bridges - Beeper Developer Docs
description: Run your own bridges with Beeper Bridge Manager
---

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](https://matrix.to/#/#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

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)

  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](#tab-panel-61)
- [Build from source](#tab-panel-62)

Download the appropriate binary for your system:

[Linux (x86\_64) ](https://github.com/beeper/bridge-manager/releases/latest/download/bbctl-linux-amd64)

[Linux (arm64) ](https://github.com/beeper/bridge-manager/releases/latest/download/bbctl-linux-arm64)

[macOS (Intel) ](https://github.com/beeper/bridge-manager/releases/latest/download/bbctl-macos-amd64)

[macOS (Apple Silicon) ](https://github.com/beeper/bridge-manager/releases/latest/download/bbctl-macos-arm64)

You can check the [GitHub releases](https://github.com/beeper/bridge-manager/releases) for the latest version, checksum(s) and source code.

Terminal window

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

### Step 2: Install dependencies

- [Debian/Ubuntu](#tab-panel-59)
- [macOS](#tab-panel-60)

Terminal window

```
sudo apt install python3 python3-venv ffmpeg
```

Terminal window

```
brew install python ffmpeg
```

### Step 3: Log in to Beeper

Terminal window

```
bbctl login
```

## Running official bridges

1. **Start a bridge**

   Terminal window

   ```
   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](https://github.com/mautrix/telegram)     |
| WhatsApp             | `whatsapp`                                  | [mautrix/whatsapp](https://github.com/mautrix/whatsapp)     |
| Signal               | `signal`                                    | [mautrix/signal](https://github.com/mautrix/signal)         |
| Discord              | `discord`                                   | [mautrix/discord](https://github.com/mautrix/discord)       |
| Slack                | `slack`                                     | [mautrix/slack](https://github.com/mautrix/slack)           |
| Google Messages      | `gmessages`, `googlemessages`, `rcs`, `sms` | [mautrix/gmessages](https://github.com/mautrix/gmessages)   |
| Google Voice         | `gvoice`, `googlevoice`                     | [mautrix/gvoice](https://github.com/mautrix/gvoice)         |
| Meta (FB/Instagram)  | `meta`, `instagram`, `facebook`             | [mautrix/meta](https://github.com/mautrix/meta)             |
| Google Chat          | `googlechat`, `gchat`                       | [mautrix/googlechat](https://github.com/mautrix/googlechat) |
| X (formerly Twitter) | `twitter`                                   | [mautrix/twitter](https://github.com/mautrix/twitter)       |
| Bluesky              | `bluesky`, `bsky`                           | [mautrix/bluesky](https://github.com/mautrix/bluesky)       |
| iMessage             | `imessage`                                  | [mautrix/imessage](https://github.com/mautrix/imessage)     |
| iMessage (Go)        | `imessagego`                                | [beeper/imessage](https://github.com/beeper/imessage)       |
| LinkedIn             | `linkedin`                                  | [mautrix/linkedin](https://github.com/mautrix/linkedin)     |
| IRC (Heisenbridge)   | `heisenbridge`, `irc`                       | [hifi/heisenbridge](https://github.com/hifi/heisenbridge)   |

## Running third-party bridges

### Bridge v2-based bridges

For bridges built with mautrix-go’s Bridge v2 framework:

1. **Generate config**

   Terminal window

   ```
   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**

   Terminal window

   ```
   bbctl register sh-<bridgename>
   ```

2. **Configure the bridge**

   Configure the bridge according to its documentation

3. **Run the proxy**

   Terminal window

   ```
   bbctl proxy -r registration.yaml
   ```

   This connects your bridge to Beeper

## Managing bridges

### Delete a bridge

This action is permanent and cannot be undone.

Terminal window

```
bbctl delete sh-<bridgename>
```

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