Mautrix-iMessage Bluebubbles Bridge Advanced Configuration

Written 12/14/2024 Updated 1/10/2025

Written by mackid1993 on Beeper (Don't DM me, I will ignore you, this is for informational purposes only and I don't have time to support this.) roc helped a lot with the auto update script.

If you don't know why your password doesn't show up in the terminal when you type sudo please close this window and don't attempt this, please follow the guide linked below or use the automated script.

This is intended to be a fully manual unscripted setup for advanced users. This will enable use of easy to use ~/.zshrc aliases to quickly and easily control the bridge as well as autoupdate bbctl as well as mautrix-imessage. This guide will work for both amd64 and arm64 Macs. It uses the --compile flag for mautrix-imessage for amd64 compatibility. This is intended for skilled users comfortable with the command line. No support will be provided. This builds off the work of all of those involved with this guide especially the launchd automation section.

Initial Folders We Will Need

We need to create folders in the following places:

/Users/Shared
/Users/Shared/Scripts
If not created also create ~/Library/LaunchAgents/

Setup bbctl and Auto Updates

1. Open a Terminal and install Homebrew

1

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

You may also be asked to install xcode command line tools. Additionally once Homebrew is installed pay attention to the terminal as it may ask you to run a few manual commands to add some things to PATH.

2. cd /Users/Shared

Now we're going to clone bbctl.

3. git clone https://github.com/beeper/bridge-manager.git

Now we install some dependencies to get bridge manager and later mautrix-imessage to compile.
You may run into issues if your version of macOS doesn't have Homebrew binaries for these dependencies, Ventura or newer is highly suggested.

4. Run one after another:
   
   ⎗

   ✓

   1 2	brew install go brew install libolm

5. Now let's get bridge-manager compiled the first time. Run one after another.
   
   ⎗

   ✓

   1 2 3

   cd /Users/Shared/bridge-manager chmod +x build.sh ./build.sh

Let it build.
chmod +x bbctl

6. Now add bbctl to PATH.

echo 'export PATH=$PATH:/Users/Shared/bridge-manager' >> ~/.zshrc && source ~/.zshrc

7. Now for our auto update script:

cd /Users/Shared/Scripts
nano update-bbctl.sh

Within nano paste the following bash script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

#!/bin/bash

# Update Homebrew and upgrade all installed packages
echo "Updating Homebrew..."
HBOUTPUT=$(brew update && yes | brew upgrade 2>&1)
echo "Homebrew Output: $HBOUTPUT"

# Navigate to the bridge-manager directory
cd /Users/Shared/bridge-manager || exit

# Fetch and pull changes, capture the output
echo "Running git fetch and pull..."
OUTPUT=$(git fetch && git pull 2>&1)

# Check if the output contains any variant of "Already up to date"
if GITOUTPUT=$(echo "$OUTPUT" | grep -E "Already up[ -]to[ -]date\.?|Current branch .* is up to date"); then
    echo "No changes detected. Skipping build."
    echo "Git output: $GITOUTPUT"
else
    echo "Git output: $OUTPUT"
    echo "Changes detected. Running build.sh..."
    ./build.sh
    echo "Done!"
fi

Save and exit out of nano.

8. Finally make our update script executable:
   chmod +x update-bbctl.sh

Create Our Launchd Plist (Thanks JasonL)

1. Navigate to the following path:

cd ~/Library/LaunchAgents

sudo nano bbctl-bluebubbles.plist
Paste in the following plist, ensure your Bluebubbles server and password are correct:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>KeepAlive</key>
        <dict>
            <key>Crashed</key>
            <true/>
        </dict>
        <key>Label</key>
        <string>bbctl-bluebubbles</string>
        <key>ProgramArguments</key>
        <array>
            <string>sh</string>
            <string>-c</string>
            <string>bbctl w; /Users/Shared/Scripts/update-bbctl.sh; sleep 15; echo Starting Bridge!!; bbctl run --compile --no-override-config --param 'bluebubbles_url=http://localhost:1234' --param 'bluebubbles_password=YOUR_PASSWORD_HERE' --param 'imessage_platform=bluebubbles' sh-imessage</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>StandardErrorPath</key>
        <string>/Users/Shared/errors.log</string>
        <key>StandardOutPath</key>
        <string>/Users/Shared/out.log</string>
        <key>WorkingDirectory</key>
        <string>/Users/Shared</string>
        <key>EnvironmentVariables</key>
        <dict>
            <key>PATH</key>
            <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/Shared/bridge-manager:/opt/homebrew/bin</string>
        </dict>
    </dict>
</plist>

Save and edit out of nano.

Edit ~/.zshrc to make the bridge easy to manage

1. sudo nano ~/.zshrc
   Paste in the following:

1
2
3
4

alias start-bb="launchctl load -w ~/Library/LaunchAgents/bbctl-bluebubbles.plist"
alias stop-bb="launchctl unload -w ~/Library/LaunchAgents/bbctl-bluebubbles.plist"
alias bb-log="tail -f /Users/Shared/out.log /Users/Shared/errors.log"
alias bb-server-restart="killall BlueBubbles ; sleep 10  && open -a BlueBubbles"

Save and exit nano.

Now once you restart your terminal:

start-bb will update bbctl and start the bridge. This will also autostart it when your Mac reboots and it will continue to run until you run stop-bb. bb-log will show the output from the bridge in real time, just like it was running in the Terminal. bb-server-restart will restart Bluebubbles. These are very useful when using a VPN server at home such as Wireguard and connecting to your home network from a cellphone, allowing you to troubleshoot your bridge using an SSH client on a cellphone in a pinch.

My favorite is to run start-bb && bb-log which will start the bridge and show the output so you can see if something is misconfigured or erroring.

Auto Restart Our Mac So Everything Stays Up to Date

Finally we want our Mac to restart weekly so the bridge restarts, bbctl and mautrix-imessage update and everything works with minimal intervention.

Open a terminal and run:

sudo pmset repeat restart U 04:00:00

Apple has a whole syntax for this, but this command will restart your Mac every Sunday at 4 AM which works well for me. You also probably want to configure autologin as well but I'm not going over that. If you got this far you can figure that part out. If you open a chat with your bridge bot @sh-imessagebot:beeper.local and send the version command, you'll see when it was compiled. If it was Sunday around 4:10 AM your Mac rebooted.

I also like to increase backfill and max attachment size, please see the original guide for instructions to do that in config.yaml.