Kordophone Monorepo

Kordophone is an iMessage bridge: a lightweight server runs on a Mac and exposes an HTTP API so non‑Apple devices can send/receive iMessages. A set of clients (Android, Linux GTK, macOS Cocoa) talk to that API. A shared Rust library powers most clients, and a mock server helps local testing.

Important: Interfacing with iMessage on macOS involves private APIs and restricted entitlements. See server/README.md for details and safety notes.

Repository Layout

Top‑level projects in this monorepo:

server/ — macOS daemon that bridges to iMessage and exposes an HTTP REST API. Written in Objective‑C/Cocoa. See server/README.md.
core/ — Rust workspace with the shared Kordophone client library and related tooling. Used by gtk/ and osx/.
gtk/ — GTK4/Libadwaita Linux desktop client built on the Rust core library.
osx/ — macOS Cocoa client that uses the Rust core library and talks to the local Kordophone client daemon via XPC.
android/ — Android client. Currently implements its own API client (does not use the Rust library yet).
mock/ — Go‑based mock server that emulates a Mac running the Kordophone server, for local development and tests.

Quick links:

Server (mac daemon): server/
Core (Rust workspace): core/
GTK client (Linux): gtk/
macOS client (Cocoa): osx/
Android client: android/
Mock server (Go): mock/

How It Works

The macOS Kordophone Server (server/) runs on a Mac with iMessage and exposes an HTTP/JSON API and a WebSocket/updates channel.
Clients connect to that server to list conversations, fetch/send messages, upload/download attachments, and receive live updates.
A Rust library in core/kordophone implements the wire protocol and client behaviors. Linux/macOS clients use this library directly; Android currently ships a native Kotlin client.
The Rust client daemon (core/kordophoned) provides local caching and IPC (D‑Bus on Linux, XPC on macOS) for GUI apps.
The mock/ server simulates the server API for local development without a Mac.

Getting Started

You can try the clients quickly against the mock server.

Run the mock server (no auth):

cd mock
go run ./...               # or: make; ./kordophone-mock

The mock server listens on http://localhost:5738.

Point a client at the mock server:

Android: open Settings in the app and set the server host to http://10.0.2.2:5738 (Android emulator) or http://<your-host-ip>:5738 if running on device. Disable auth unless you started the mock with --auth.
GTK (Linux): build and run the GTK app from gtk/ (see its README) and configure it to use the local daemon backed by the server URL.
macOS (Cocoa): build the app in osx/ (see osx/README.md).

To use a real Mac server instead, set your client’s server URL to the host running server/ with the correct scheme/port and authentication.

Building

Below are brief notes. Each subproject’s README has more detail.

Server (macOS): open server/MessagesBridge.xcodeproj in Xcode. See server/README.md for entitlements, SSL, and running.
Core (Rust): install Rust (stable) and run cargo build inside core/. See core/README.md.
GTK (Linux): see gtk/README.md for RPM build via rpmbuild -ba dist/rpm/kordophone.spec.
macOS (Cocoa): open osx/kordophone2.xcodeproj in Xcode. See osx/README.md.
Android: open android/ in Android Studio and build. See android/README.md for configuration.
Mock server (Go): cd mock && go run ./... or make.

Security and Entitlements

The macOS server uses private APIs and restricted entitlements. On production macOS builds, processes with restricted entitlements can be killed by the kernel; development requires workarounds (e.g., swizzling, hooking imagent) and careful code signing. See server/README.md for instructions and caveats.

Status

Android client: ships its own API client (not yet using Rust core).
GTK + macOS clients: use the Rust core library and integrate with the kordophoned client daemon for caching/IPC.
Mock server: useful for development; implements common endpoints and WebSocket updates.

Contributing

Issues and PRs are welcome. If you add a new client or endpoint, please update relevant READMEs and link it from this root README. Prefer small, focused changes and keep style consistent with the existing code.

4.3 KiB Raw Blame History Unescape Escape