Relay
The relay is a mailbox for ciphertext between your devices. Run your own with one binary.
The relay stores and forwards encrypted blobs between your devices. One device needs no relay at all. You need one to pair a second computer or a phone.
Because everything is encrypted before upload, a relay needs no trust beyond staying up.
Point Lorca at a relay
Set Settings › Advanced › Relay URL on your first device, or the LORCA_RELAY_URL environment variable for the CLI. Devices you pair afterwards learn the URL from the pairing code.
Run your own
The relay is a single binary, lorca-relay, with SQLite built in:
lorca-relay --bind 0.0.0.0:8787 --db lorca-relay.dbPut it behind HTTPS with a reverse proxy such as Caddy or nginx (WebSocket upgrades must pass through), and add --trust-proxy so rate limits see real client addresses.
| Option | What it does |
|---|---|
--bind | Address and port to listen on. |
--db | A SQLite file path, or a postgres:// URL. |
LORCA_RELAY_SECRET | Signs session tokens. Set it so tokens survive a restart. |
--quota-bytes | Storage cap per identity; 5 GiB by default. 0 for none. |
--concurrent-uploads | Attachments over 1 MiB handled at once (3 by default), which bounds the memory they take. |
--files-dir | Where attachment ciphertext goes. Defaults to a folder beside the database. |
--s3-bucket, --s3-endpoint | Keep attachments in S3, R2, or MinIO instead. |
--min-protocol | Turns away Lorca versions that speak an older relay protocol; their apps ask for an update. |
--inactive-days | Deletes an account nothing has touched for this long (365 by default; 0 for never). Devices keep their own copy. |
--ip-per-minute, --identity-per-second | Rate limits. |
LORCA_RELAY_METRICS_TOKEN | Serves GET /metrics for Prometheus to whoever sends this bearer token. |
Postgres
Use a postgres:// URL to run several relay processes against one database, for deploys without a gap. They must share LORCA_RELAY_SECRET and keep attachments in an S3-compatible bucket.
Push notifications
To send pushes to the phone app, give the relay an APNs key (--apns-key, --apns-key-id, --apns-team-id) or a Firebase service account (--fcm-service-account). Each key is the path of its file or the text itself, so LORCA_RELAY_APNS_KEY and LORCA_RELAY_FCM_SERVICE_ACCOUNT can carry them where there is no disk to keep a file on. Without them everything else works and phones get no pushes.
Monitoring
With LORCA_RELAY_METRICS_TOKEN set, GET /metrics answers a scraper that sends the token as a bearer with Prometheus text: identities and machines, blobs and bytes by kind, open sockets, requests by route and status, rate-limit refusals, pushes sent and failed, and what the housekeeping sweeps removed. The relay cannot read what it stores, so these numbers are what there is to watch.
Limits
You can attach files up to 100 MiB each. Attachments transfer as encrypted binary data. The relay accepts the file plus its 40-byte encryption envelope; message and other non-file blobs are limited to 4 MiB of ciphertext.