iMessage bridge setup (macOS)

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 a reasonably new version of macOS.
  • The bridge requires full disk access in privacy settings to read your chat database.
• 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).

Installation

You may either compile the bridge manually or download a prebuilt executable from the mau.dev CI.

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).

Downloading a prebuilt executable

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.
   • There are three entries: universal, arm64 (Apple Silicon) and amd64 (Intel). You can either pick universal, or the specific architecture depending on what Mac you have.
3. Extract the downloaded zip file into a new directory.

Configuring and running

1. Copy example-config.yaml to config.yaml
2. Update the config to your liking.
   • You need to make sure that the address and domain field point to your homeserver.
   • You will also need to add your user ID to the bridge section.
3. Generate the appservice registration file by running ./mautrix-imessage -g.
   • You can use the -c and -r flags to change the location of the config and registration files. They default to config.yaml and registration.yaml respectively.
4. Set up mautrix-wsproxy.
5. Update your registration file so the url field points to wsproxy (e.g. http://localhost:29331, this is where your homeserver reaches wsproxy), and make sure the websocket_proxy field in the bridge config also points to wsproxy (e.g. ws://matrix.example.com:29331, where the bridge reaches wsproxy).
6. Register the bridge on your homeserver (see Registering appservices).
7. Run the bridge with ./mautrix-imessage.
8. If/when the bridge fails to initialize the iMessage connector with the operation not permitted error, go to System Preferences -> Security & Privacy -> Privacy -> Full Disk Access and grant access to the terminal you're running the bridge in.