LorcaDocs

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

Put 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

OptionWhat it does
--bindAddress and port to listen on.
--dbA SQLite file path, or a postgres:// URL.
LORCA_RELAY_SECRETSigns session tokens. Set it so tokens survive a restart.
--quota-bytesStorage cap per identity; 5 GiB by default. 0 for none.
--concurrent-uploadsAttachments over 1 MiB handled at once (3 by default), which bounds the memory they take.
--files-dirWhere attachment ciphertext goes. Defaults to a folder beside the database.
--s3-bucket, --s3-endpointKeep attachments in S3, R2, or MinIO instead.
--min-protocolTurns away Lorca versions that speak an older relay protocol; their apps ask for an update.
--inactive-daysDeletes an account nothing has touched for this long (365 by default; 0 for never). Devices keep their own copy.
--ip-per-minute, --identity-per-secondRate limits.
LORCA_RELAY_METRICS_TOKENServes 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 on 127.0.0.1:8984/hook and takes the key as Authorization: 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:

VariableWhat it sets
LORCA_MODELS_URLWhere Lorca checks for a newer model catalog. Default https://lorca.app/models/v1.json.
LORCA_MARKETPLACE_URLWhere Lorca checks for a newer marketplace. Default https://lorca.app/marketplace/v1.json.

On this page