BeansDocs

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

OptionWhat it does
--bindAddress and port to listen on.
--dbA SQLite file path, or a postgres:// URL.
BEANS_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 Beans 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.
BEANS_RELAY_METRICS_TOKENServes 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.

On this page