iMessage bridge setup (macOS without SIP)
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.
- 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.
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.
- Clone the repo with
git clone https://github.com/mautrix/imessage.git.
- Enter the directory (
./build.shto fetch Go dependencies and compile (
build.shwill simply call
go buildwith some additional flags).
- Refer to the Barcelona build instructions for building Barcelona.
Downloading prebuilt executables
- Go to https://mau.dev/mautrix/imessage/-/pipelines?scope=branches&page=1
- Find the entry for the
masterbranch and click the download button on the right-hand side in the list and choose "build universal".
- Extract the downloaded zip file into a new directory.
darwin-barcelona-mautrixfrom https://github.com/beeper/barcelona/actions (latest direct download).
Disabling SIP and AMFI
Disabling SIP and AMFI will make your Mac significantly less secure.
- Boot into recovery mode (hold Command+R while booting) and open a terminal
csrutil disableto disable SIP
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=0to prevent those from breaking.
- If you run other things like Electron apps on the Mac (which you definitely should not), you may want to add
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,
EFI/OC/config.plist) and change the key
boot-args to add
<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
- Follow steps 1-6 from the normal macOS setup
- Install Barcelona's com.apple.security.xpc.plist to
- In the
imessagesection of the config, change
imessage_rest_pathto the path to the
darwin-barcelona-mautrixexecutable you downloaded or compiled.
- Run the bridge with