Relay
Your devices sync through Lorca's relay, which can't read your chats. You can also run your own.
Your devices sync through Lorca's relay at relay.lorca.app. It stores and forwards the encrypted data your devices exchange, and sends your phone its notifications. It also takes the requests for your pull request watches and routines' webhooks and encrypts each one for your computer. The apps use it from the start, so there is nothing to set up: a device you pair learns it from the pairing code.
Everything is encrypted before upload, so the relay can't read your chats, bots, files, or provider keys. Security lists what it does see.
Limits
- You can attach files up to 100 MiB each. Messages and other data are limited to 4 MiB each, encrypted.
- An account nothing has touched for a year, with no device connected and nothing synced, is deleted from the relay. Your devices keep what they have, and the first one that comes back registers the account again.
Run your own relay
Lorca's relay is the same program you can run yourself: a single binary, lorca-relay, with SQLite built in. Your devices then sync through your server instead.
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.
Point Lorca at it
Set Settings › Advanced › Relay URL on your first device before you pair the others, or the LORCA_RELAY_URL environment variable on a computer with only the command line. Devices you pair afterwards learn the URL from the pairing code. A bot shared as a link from your relay names it in the link, so lorca.app opens it from there.
Options
| 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. |
Pull request watches and webhooks
Lorca's relay hosts the receivers for pull request watches and routines' webhooks. Yours can too: LORCA_RELAY_PUBLIC_URL, its own public address, turns on webhooks (<address>/webhooks/<id>), and a GitHub App of your own, registered from crates/relay/github-app.json with its URLs on your relay's address (/webhooks/github and /webhooks/github/callback), turns on watches through LORCA_RELAY_GITHUB_APP_ID, LORCA_RELAY_GITHUB_APP_SLUG, LORCA_RELAY_GITHUB_CLIENT_ID, LORCA_RELAY_GITHUB_CLIENT_SECRET, LORCA_RELAY_GITHUB_WEBHOOK_SECRET, and LORCA_RELAY_GITHUB_PRIVATE_KEY.
Without them, such a routine says Your gateway, and its events come through the gateway you run on one of your computers. The bot names the routine's subscription; export its route with lorca events route <id> route.json, then:
- For a watch, run the gateway with
--github-secret-file <secret> --routine, and add a webhook to the repository with your public URL, JSON content, the same secret, and the events Pull requests, Pull request reviews, Pull request review comments and threads, Issue comments, Check runs, Check suites, Statuses, and Workflow runs. - For a webhook, run it with
--webhook-key-file <key>(a random key of at least 32 characters). It listens on127.0.0.1:8984/hookand takes the key asAuthorization: Bearer <key>.
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.
The model catalog and the marketplace
Devices check lorca.app for a newer model catalog and marketplace. To serve your own copies, point the command line at them:
| Variable | What it sets |
|---|---|
LORCA_MODELS_URL | Where Lorca checks for a newer model catalog. Default https://lorca.app/models/v1.json. |
LORCA_MARKETPLACE_URL | Where Lorca checks for a newer marketplace. Default https://lorca.app/marketplace/v1.json. |