DOCSEARCHbyAlgolia
Submit Docs

Beeper Bridge Manager (bbctl)

repository·main·Indexed 23 days ago

https://github.com/beeper/bridge-manager

A tool for running self-hosted Matrix bridges that connect to the Beeper.com server. It allows users to host official or 3rd party bridges to maintain control over security and encryption. The bbctl CLI supports installing, configuring, and running bridges via native binaries or Docker, and provides utilities for managing bridgev2-based and custom non-bridgev2 bridges.

Tokens
4.9K
Snippets
4
Records
35
Agent score
79%

What's inside beeper-bridge-manager

  1. Run official Beeper bridges

    main

    To run an official Beeper bridge (like WhatsApp, Signal, or Telegram), follow these steps:

    1. Install Dependencies:
      • Python 3 with the venv module (e.g., sudo apt install python3 python3-venv on Debian).
      • ffmpeg (required for media conversion, e.g., sudo apt install ffmpeg on Debian or brew install ffmpeg on macOS).
    2. Run the bridge: Use bbctl run <name>.
      • The <name> must start with sh- and consist of a-z, 0-9, and -.
      • If the name contains a known identifier (see Official bridge list), the type is automatically detected. Otherwise, specify it with --type <type>.
    3. Configure the bridge: Currently, configuration is done by sending a DM to the bridge bot at @<name>bot:beeper.local.

    Note: Bridges run in the foreground. You must keep the process active (e.g., using tmux). Local data is stored in ~/.local/share/bbctl (configurable via ~/.config/bbctl.json).

  2. Run 3rd party bridgev2-based bridges

    main

    If your 3rd party bridge is built on the mautrix-go bridgev2 framework, bbctl can generate most of the configuration for you.

    1. Generate config: Run bbctl config --type bridgev2 <name>.
      • <name> must start with sh-.
      • The bridge user ID namespace will be @<name>_.+:beeper.local.
      • The bridge bot will be @<name>bot:beeper.local.
    2. Complete configuration: Manually add the network section to the generated file with your bridge-specific settings.
    3. Run: Run the bridge normally using your preferred method.

  3. Install bbctl

    main

    You can install the bbctl CLI tool using Homebrew, by downloading binaries, or by building from source.

    Prerequisites:

    • Building from source requires Go 1.25 or higher.
    • Supported platforms: Linux and macOS (amd64 and arm64).
    • Windows is not supported natively; use WSL instead.

    Installation methods:

    1. Homebrew: brew install beeper/tap/bbctl
    2. Binaries: Download from GitHub releases or actions.
    3. Build from source:
      git clone <repository>
./build.sh
    brew install beeper/tap/bbctl

  4. Run bridge-manager using Docker

    main

    You can run bridge-manager via Docker to wrap bbctl run. This is useful for manual deployments or automated environments like the Fly deployer.

    To run a bridge, you must:

    1. Mount a local directory to /data inside the container to persist bridge binaries, configuration, and the database.
    2. Provide your Beeper access token via the MATRIX_ACCESS_TOKEN environment variable.
    3. Specify the Docker image and the name of the bridge you wish to run.

    Finding your Beeper access token:

    • Check ~/.config/bbctl/config.json on your local machine.
    • Or find it in Beeper Desktop settings -> Help & About.

    Permissions: The container works with any user as long as the mounted /data directory is writable. You can use the standard Docker --user flag to specify a specific UID/GID.

    docker run \
	-v $(pwd):/data \
	-e MATRIX_ACCESS_TOKEN=... \
	ghcr.io/beeper/bridge-manager sh-telegram

  5. Delete a bridge

    main

    To remove a bridge and its traces from Beeper servers:

    1. Standard deletion: Run bbctl delete <name>. This erases rooms and ghost users from Beeper servers. For official bridges, it also deletes local data (config, database, venv).
    2. Local-only deletion: If you created the bridge database with bbctl run -l, run bbctl delete -l from the same working directory.

    Warning: Deleting via the Beeper client settings does not delete the local bridge database. If you re-add a bridge later without clearing the old local database, you may encounter errors because the bridge will attempt to join rooms it is no longer a member of.

  6. Run 3rd party custom bridges (non-bridgev2)

    main

    For custom bridges that do not use bridgev2, you must manually register the appservice and use a proxy to connect the Beeper websocket to the bridge's HTTP interface.

    1. Register the bridge: Run bbctl register <name> to generate an appservice registration file. Use --json if you need to automate fetching the homeserver URL.
    2. Configure the bridge: Follow the bridge's own documentation to set it up.
    3. Update registration: Modify the generated registration file to point to your bridge's local listening URL (e.g., url: http://localhost:8080).
    4. Start the proxy: Run bbctl proxy -r <registration_file>.yaml. This connects to Beeper via websocket and pushes events to your bridge via HTTP.

  8. Understand the bbctl configuration structure

    main

    The bbctl configuration is stored as a JSON file and contains a unique device_id and a map of environments. Each environment defines how to connect to a specific Beeper cluster.

    EnvConfig Fields

    When configuring an environment, you can specify:

    • cluster_id: The ID of the cluster.
    • username: Your Beeper username.
    • access_token: An authentication token. Valid tokens typically start with syt_ or bat_.
    • bridge_data_dir: The directory where bridge-specific data is stored. If not provided, it defaults to UserDataDir/bbctl/<environment_name>.
    • database_dir: (Optional) The directory for the database.
    • desktop_data_dir: (Optional) The directory for desktop-related data. If this is set, the environment is considered to use a desktop login.

  9. How the interactive CLI mode works

    main

    The bridge-manager interactive CLI mode uses the Ask function to automatically prompt users for missing or unset command-line flags.

    When Ask is called within a command context, it traverses the command lineage (from the application level down to the specific command) to identify flags that are defined as interactive.Flag types but have not yet been set by the user via standard CLI arguments.

    For each such flag, the CLI will:

    1. Prompt the user using the flag's associated survey.Prompt.
    2. Apply any survey.Validator or survey.Transformer defined on the flag.
    3. Automatically set the flag's value in the cli.Context using the user's input, allowing the command to proceed as if the flag had been provided via the command line.

  10. Configure the bbctl data directory

    main

    The bbctl tool uses a data directory to store configuration and bridge data. You can override the default location by setting the BBCTL_DATA_HOME environment variable.

    If BBCTL_DATA_HOME is not set, the tool determines the directory based on your operating system:

    • Windows/macOS: Uses the standard user configuration directory.
    • Linux/Other: Uses $XDG_DATA_HOME. If that is not set, it defaults to $HOME/.local/share.

  11. Develop bridges locally with `--local-dev`

    main

    When developing a bridge, use the --local-dev flag. This changes the behavior of bbctl run in several ways:

    1. Working Directory: Instead of using the central bridge data directory, bbctl uses your current working directory as the bridge directory.
    2. Config Protection: It defaults to --no-override-config, meaning it won't overwrite your existing config.yaml.
    3. Binary Selection: For Go bridges, it attempts to run the binary found in your current directory rather than downloading a managed version.
    4. Python Setup: For Python bridges, it creates the virtual environment inside your current directory as .venv instead of venv.

  12. Compile bridges locally with `--compile`

    main

    If you are on an architecture for which pre-built binaries are not available in CI, use the --compile flag.

    bbctl will:

    1. Clone the appropriate bridge repository from GitHub (e.g., mautrix/<bridge-type>).
    2. Pull the latest changes.
    3. Run the bridge's build script (e.g., ./build.sh or ./build-ig.sh for Instagram).
    4. Place the resulting binary in the bridge's data directory.

    Note: This is intended for users on unsupported architectures, not for active development. For active development, use --local-dev instead.