iMessage bridge setup (macOS without SIP)

Note: Barcelona is no longer maintained and may not work on recent macOS versions. The normal Mac connector will likely work better.

Please note that everything in these docs are meant for server admins who want to self-host the bridge. If you're just looking to use the bridges, check out Beeper, which provides fully managed instances of all of these bridges.

Requirements

  • A computer running macOS 11 or higher, with SIP and AMFI disabled (see instructions below).
  • A Matrix homeserver that supports application services (e.g. Synapse). You need access to register an appservice, which usually involves editing the homeserver config file.
  • A websocket proxy to receive appservice transactions.

If you want to compile the bridge manually (which is not required), you'll also need:

  • Go 1.19+ (download & installation instructions at https://go.dev/doc/install).
  • libolm3 with dev headers (brew install libolm).
  • Optionally libheif with dev headers for heif -> jpeg conversion (brew install libheif).
  • Xcode 14.2+ if you want to build Barcelona yourself.

Installation

This form of the bridge consists of two components: Barcelona for connecting to iMessage and mautrix-imessage for connecting to Matrix. mautrix-imessage will run Barcelona as a subprocess and they communicate over stdio.

You may either compile the bridge and Barcelona manually, or download prebuilt executables from the mau.dev CI and GitHub actions respectively.

Because Barcelona hooks into Apple's private APIs, you must disable SIP (System Integrity Protection) and AMFI (Apple Mobile File Integrity) on the Mac for it to work. Disabling SIP will make your Mac less secure, so you should only do it on a Mac that you won't use for anything else.

Compiling manually

  1. Clone the repo with git clone https://github.com/mautrix/imessage.git.
  2. Enter the directory (cd mautrix-imessage).
  3. Run ./build.sh to fetch Go dependencies and compile (build.sh will simply call go build with some additional flags).
  4. Refer to the Barcelona build instructions for building Barcelona.

Downloading prebuilt executables

  1. Go to https://mau.dev/mautrix/imessage/-/pipelines?scope=branches&page=1
  2. Find the entry for the master branch and click the download button on the right-hand side in the list and choose "build universal".
  3. Extract the downloaded zip file into a new directory.
  4. Download darwin-barcelona-mautrix from https://github.com/beeper/barcelona/actions (latest direct download).

Disabling SIP and AMFI

Disabling SIP and AMFI will make your Mac significantly less secure.

  1. Boot into recovery mode (hold Command+R while booting) and open a terminal
  2. Run csrutil disable to disable SIP
  3. Run nvram boot-args="amfi_get_out_of_my_way=0x1" to disable AMFI
    • If you run other things like Electron apps on the Mac (which you definitely should not), you may want to add ipc_control_port_options=0 to prevent those from breaking.

If you are running macOS in a VM (e.g. through OSX-KVM) you may need to disable AMFI with a boot option. Assuming you are using OSX-KVM and OpenCore, open the config.plist (in EFI/OC/config.plist) and change the key boot-args to add amfi_get_out_of_my_way=0x1:

<key>boot-args</key>
<string>-v keepsyms=1 tlbto_us=0 vti=9 amfi_get_out_of_my_way=0x1</string>

You can also refer to Apple's official documentation on disabling SIP.

Configuring and running

  1. Follow steps 1-6 from the normal macOS setup
  2. Install Barcelona's com.apple.security.xpc.plist to /Library/Preferences/com.apple.security.xpc.plist
  3. In the imessage section of the config, change platform to mac-nosip and set imessage_rest_path to the path to the darwin-barcelona-mautrix executable you downloaded or compiled.
  4. Run the bridge with ./mautrix-imessage.