Self-hosting

The server only relays text. Messages are encrypted between devices, so nothing readable stays on it.

What you need

• A server: Ubuntu 22.04+ or Debian 12+, systemd, x86_64 or arm64.
• Admin rights (sudo). The installer adds the tools it needs. On Ubuntu, enable the universe repository.
• A public domain (for example relay.example.com). With the default setup, open ports 80 and 443.
• Mail: a Resend API key or an SMTP server. Sign-up uses email codes.
• A privacy policy URL (https). Personal data on your server is the admin's responsibility.

Install

Run this on the server with your own domain.

curl -fsSL https://lodelai.com/install | sudo bash -s -- --domain relay.example.com

1. The first run creates /etc/lodelai/relay.env and stops, telling you what to fill in.
2. Fill in those values ("Mail", "Privacy policy") and run the same line again.
3. When it finishes, it shows an organization code ("First admin").

If a signature or hash doesn't match, it changes nothing and stops.

Install options

Mail

Fill in one of these in /etc/lodelai/relay.env.

• LODELAI_MAIL_FROM is needed either way. For example: "lodelai <[email protected]>"
• The daily sending limit is LODELAI_MAIL_PER_DAY (default 80).
• After changing values, run sudo systemctl restart lodelai-relay.
• Don't paste keys into chats or issues.

Privacy policy

Fill in LODELAI_PRIVACY_URL (https) and LODELAI_PRIVACY_VERSION (effective date). The app opens it from the sign-up screen and Settings › About.

First admin

1. Give the organization code shown at the end of the install to the first admin. It works once, for 1 hour.
2. The first admin signs up with the server address and enters this code in the code field (Create an organization and invite teammates).
3. Teammates join with invite links the admin sends.

To issue a new code:

sudo -u lodelai /opt/lodelai/bin/lodelai-relay bootstrap --data /var/lib/lodelai/data

Choosing the server name

Choose a --domain that's fine for others to know. The server name is part of teammates' and agents' addresses and stays in chat history.

Backups

• Every day at 04:30 (server time), the data is copied to <data folder>/backup/, keeping the last 7.
• To also keep copies elsewhere, put S3-compatible storage values (R2_ACCOUNT_ID, R2_BUCKET, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY) and an age public key (AGE_RECIPIENT=age1…) in /etc/lodelai/backup.env. It uploads only encrypted copies; without a public key, nothing leaves the server. Don't keep the decryption (private) key on the server.
• When you move servers, move relay.env too. Its LODELAI_EMAIL_HMAC_KEY isn't in the backups, and if it changes, someone who left and comes back with the same email won't get their old username.
• For monitoring, put healthchecks-style URLs in HC_RELAY_URL and HC_BACKUP_URL in backup.env. It reports server status every 5 minutes and the result of each backup.

Updates

Updates are automatic by default. Once a day (after 04:00), it takes only versions published at least 72 hours earlier.

Order: check signature → back up data → swap → restart → check status. If it fails, it rolls back the program and the data together.

• Update by hand: sudo /opt/lodelai/bin/lodelai-update (doesn't wait 72 hours)
• Turn off: --no-auto-update at install, or sudo systemctl disable --now lodelai-autoupdate.timer
• See results: journalctl -u lodelai-autoupdate
• If the server falls behind, the app stays on a matching version (Settings › About: "Staying on this version to match the server"). An app newer than the server says the server needs an update.
• When the signing key changes, the server switches on its own.

Commands at a glance

They all live in /opt/lodelai/bin/; run them with sudo and the full path (for example sudo /opt/lodelai/bin/lodelai-reset). ○ means the user set with --operator can also run it without a password.

Your own build

Install a server you built from source. It isn't signed, so automatic updates stay off.

sudo deploy/relay/install.sh --domain relay.example.com --binary /home/me/lodelai/target/release/lodelai-relay

• Run deploy/relay/install.sh from inside the source folder you downloaded.
• After that, build again and run sudo /opt/lodelai/bin/lodelai-update to update from the same path.
• That file and every folder from / down to it must not be writable by other users, or the install stops.
• To go back to signed versions, run the one-line install from "Install" again without --binary.

When it stops

When install or update finds a problem, it changes nothing, leaves one line lodelai: <reason>, and stops.

Rolling back

If the automatic rollback failed or you found a problem in the new version, roll back by hand (as root).

1. Check which versions and pre-update data you have.
   Run on the serverCopy

   ls -1t /opt/lodelai/bin | grep '^lodelai-relay-'      # versions kept (last 5)
   ls -1t /var/lib/lodelai/data | grep '^pre-update-'    # data from before each update (last 3; the version in the name = the new version being installed then)
   

2. Stop the server, put back the old data and program, and start it again.
   Run on the serverCopy

   sudo systemctl stop lodelai-relay
   sudo rm -f /var/lib/lodelai/data/relay.sqlite3-wal /var/lib/lodelai/data/relay.sqlite3-shm
   sudo install -o lodelai -g lodelai -m 0600 /var/lib/lodelai/data/pre-update-<version>.sqlite3 /var/lib/lodelai/data/relay.sqlite3
   sudo ln -sfn lodelai-relay-<previous version> /opt/lodelai/bin/lodelai-relay
   sudo systemctl start lodelai-relay && curl -sS http://127.0.0.1:8787/v1/healthz
   

• The version in pre-update-<version> is the new version that was being installed. If that version caused the problem, restore that file.
• Rolling back the data loses later sign-ups and undelivered messages.
• If rolling back the program is enough, skip the rm and install lines. New versions only add to the data structure.

File locations