Kordophone/README.md

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

1. The macOS Kordophone Server (server/) runs on a Mac with iMessage and exposes an HTTP/JSON API and a WebSocket/updates channel.
2. Clients connect to that server to list conversations, fetch/send messages, upload/download attachments, and receive live updates.
3. 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.
4. The Rust client daemon (core/kordophoned) provides local caching and IPC (D‑Bus on Linux, XPC on macOS) for GUI apps.
5. 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.

1. Run the mock server (no auth):

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

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

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