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 Beans at a relay
Set Settings › Advanced › Relay URL on your first device, or the BEANS_RELAY_URL environment variable for the CLI. Devices you pair afterwards learn the URL from the pairing code.
Account routes, including registration, challenge, pairing mailboxes and sync, require unique valid Beans-Protocol: 5 and Beans-Format: beans-v2 headers. Effective floors cannot fall below 5. Old-format peers are incompatible, with no automatic migration or production rollout. SQLite requires BNR2 application id 0x424E5232 before opening; Postgres requires exactly one beans-v2 row in beans_storage_format, initialized only in a truly empty schema. Existing unmarked storage is rejected before DDL/recovery without changing it.
Run your own
The relay is a single binary, beans-relay, with SQLite built in:
beans-relay --bind 0.0.0.0:8787 --db beans-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. |
BEANS_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 Beans 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. |
BEANS_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 BEANS_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 BEANS_RELAY_APNS_KEY and BEANS_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 BEANS_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.