yetone/alma-relay

Alma Relay is a self-hostable relay for Alma's Remote Access feature. The desktop Alma opens an outbound WebSocket to the relay; the phone app reaches that same relay over HTTPS/WSS, and the relay passes requests — HTTP, streaming SSE and WebSockets — down the desktop's existing connection. You would run it when you want remote control of your desktop Alma to stay on infrastructure you choose, in a region closer to you, rather than depending on the hosted relay.alma.now service (README).

Deployment paths and their requirements

The project documents three ways to run the same relay, and they need different things:

• Cloudflare Workers, presented as free with no server. It uses SQLite-backed Durable Objects and WebSocket hibernation, and the fixed request-body cap is 24 MB. TLS and a *.workers.dev hostname are included; a custom domain needs a routes entry (README).
• Docker with automatic HTTPS on a VPS with ports 80 and 443 open and DNS pointing at the host; Caddy obtains and renews the certificate (README).
• Behind your own reverse proxy, either with the published container or with Node ≥ 20. Your proxy must allow WebSockets and must not buffer responses; the README gives nginx and Caddy examples and a /healthz check (README).

Everything is configured through environment variables, and all of them are optional. Two affect who can use the relay: with no key set, anyone who knows the address can open tunnels (though your 256-bit connect code is still needed to reach your desktop); RELAY_REGISTRATION_KEY gates registration with a shared key; RELAY_TOKEN_SECRET instead signs per-user JWTs, which suits one relay shared by a team and allows revoking all tokens by rotating the secret (README).

Security model and limits

With end-to-end encryption on — the default for new pairings — phone and desktop do an authenticated ECDH handshake and derive an AES-256-GCM session, with the connect code mixed into key derivation. The relay operator sees ciphertext, and codes, tokens and traffic are never written to disk or logs (README). That guarantee depends on client versions: Alma 0.4.329 or later is required, because older desktops still answered plaintext requests issued by the relay itself. TLS is still advised, since it hides routing metadata even though content stays protected (README).

Two features have additional constraints. Phone notifications go through Apple Push, which only accepts keys from the team that signs the app, so a self-hosted relay cannot notify the official Alma iOS app — everything else works; a self-built iOS app can supply its own APNs key (README). The live browser view over WebRTC usually needs a TURN server: the Docker setup includes coturn and the required ports, while Cloudflare users must run coturn elsewhere and pass credentials via configuration (README).

Practical notes

Phones paired before switching relays must scan a new pairing QR code, since the pairing link carries the relay address (README). The license is MIT (LICENSE). The repository offers a protocol document for writing your own relay or agent, and an end-to-end test suite for both editions (README).