Using relaii

Get started with your Space

Join your team, find your conversations and make relaii work for you. If you manage a Space, you’ll also find help with setup, access, backups and updates.

Using an AI agent? Point it to docs.md, a Markdown edition of this guide written for agents.

Join or create a Space

Your Space is your team’s relaii installation. It has its own address, accounts, channels and files. Ask your administrator for the address, such as chat.example.no.

Join an existing team

1. Open the invitation link your administrator sent you and create your account.
2. To sign in again, open your Space address in a browser, or enter that address in the relaii app.
3. Sign in with your account details. If asked, enter the code from your authenticator app or a recovery code.

Your account belongs to that Space. If you use more than one Space, sign in to each separately and use the Space switcher in the app to move between them.

If you forget your password, use the password reset option on your Space’s sign-in page. If it is unavailable or the email does not arrive, contact your Space administrator.

Set up a Space for your team

Follow the installation guide to run relaii on your own server. Open your new Space address, create the owner account and complete setup before inviting your team.

Messages, channels and files

Use channels to keep a project or topic together. Use a direct message for a conversation with one person, or a group conversation for a smaller group.

1. Open a channel from the channel list. Use Browse to find public channels available in your Space. Ask a channel manager for an invitation to a private channel.
2. Write your message and send it. You can use Markdown for bold text, lists and code, and @ to mention someone.
3. Attach a file to share it with the conversation. People need access to the channel to open its files.
4. Use the message menu to edit or delete a message you sent, or save it for later. Available actions depend on your permissions.

To start a channel, choose New channel, enter a name and choose who can see it. If that action is unavailable, ask your administrator about channel creation permissions.

In an archived channel, you can read the history but cannot send new messages. Ask a channel manager to restore it if the conversation needs to continue.

Find a message or file

Open Search and enter a word or phrase. Add filters to narrow the results:

Filter	Use it to find
from:alex	Messages from Alex.
in:#design	Messages in the design channel.
after:2026-09-01	Messages after a date. Use before: for an upper date limit.
has:file	Messages with attachments.

Combine filters with your search text, for example launch in:#design has:file. Results include only conversations you have permission to read.

Shared links and widgets

Open Links & widgets in a channel, or Content on Android, to find shared links and embedded information. Channel managers can maintain these items. To connect an external dashboard or notification service, follow the integration guide.

Notifications and offline reading

Choose your notification preference in Settings. You can also mute an individual conversation or change its notification preference without changing the rest of your Space.

In the Apple and Android apps, notification detail is set separately for each account and device. Clean shows a general activity alert. Informational includes a sender and excerpt when your app and Space support previews. If a preview is unavailable, the notification uses the general alert.

When you are offline, the Apple and Android apps let you read messages already downloaded to that device. Reconnect to load new messages and send replies. You can clear downloaded messages in Settings; signing out or forgetting the account removes its local cache.

Commands

Type / in a conversation to see available commands. Use /help for help, /mute to silence the conversation, and /unmute to turn notifications back on. These commands respond only to you.

/me action and /shrug text send messages to the conversation. To send a message that starts with a literal slash, begin with //.

Manage your Space

You need an administrator account to open Admin. Use it to invite people, manage accounts and access, check storage and connect your Space to another organisation.

Task	What to do
Invite people	Create invitations in Admin and send them by email or share their invitation links. Review the assigned role before sending.
Manage access	Review registration rules, member permissions and multi-factor authentication requirements. Disable accounts when people leave your team.
Check storage	Open the storage panel to see usage and upload limits. Include your attachment storage in your backup plan.
Connect another Space	Work with its administrator to approve the connection and choose channels to share. Follow the federation guide.
Add an integration	Create a webhook or API key with access to the channels it needs. Follow the API guide.

Change server configuration

If you manage the server, installation settings are in /opt/relaii/.env. Back up the Space before changing them, then restart relaii to apply your changes:

sudo nano /opt/relaii/.env
sudo relaii restart

Keep the domain stable: it is your team’s sign-in address and the identity used by connected Spaces. Keep the generated encryption and identity keys unchanged so existing messages and connections remain accessible.

Set up invitation and password reset emails

Get SMTP credentials from your mail provider and set the following values in /opt/relaii/.env. This example uses STARTTLS on port 587; use the connection settings required by your provider.

SMTP_HOST=smtp.example.no
SMTP_PORT=587
SMTP_USERNAME=your-smtp-username
SMTP_PASSWORD=your-smtp-password
SMTP_FROM=chat@example.no
SMTP_TLS=true
SMTP_SSL=false

Restart relaii, send a test invitation and confirm it arrives. Without SMTP, you can share invitation links yourself, but password reset emails cannot be delivered.

Backups and updates

Run these commands on the server that hosts your Space. Begin by checking its version and health:

sudo relaii version
sudo relaii doctor

Take a backup

sudo relaii backup

Enter and confirm a backup passphrase when prompted. The command writes an encrypted archive to /var/lib/relaii/backups and prints its path. Save a copy off the server and keep the passphrase separately, for example in your organisation’s password manager.

The archive includes the database, configuration, message encryption key and federation identity. Attachment files need a separate backup. Back up the local attachment storage or your S3 bucket as well. If you have used both storage types, keep backups of both.

For scheduled backups, put the passphrase in a file readable only by root and use --passphrase-file. Keep an independent copy of that passphrase. The following command keeps the 14 newest archives in the backup directory:

sudo relaii backup --passphrase-file /root/.relaii-backup-pass --keep 14

Install an update

Read the release notes, choose a maintenance window and have your backup passphrase ready. Then run:

sudo relaii update

relaii takes a backup before installing the update and checks the Space after restarting. If the backup fails, the update stops. After a successful update, sign in, open a conversation and check that you can send a message and open an attachment.

Restore from a backup

Restoring replaces the current database and configuration with the backup. Arrange downtime and confirm which backup you need before proceeding. You need the archive, its passphrase and the corresponding attachment backup.

1. Prepare a relaii installation using the version recorded with your backup. Rehearse recovery on an isolated server before you need to recover your live Space.
2. Copy the archive to that server. Replace BACKUP_FILE.tar.zst.enc below with its actual path, then run the restore command and follow its prompts.
3. Restore the attachment storage separately. Keep a rehearsal isolated from your live Space and connected partners.
4. Run sudo relaii doctor, sign in, check message history and open an attachment. For a live recovery, also check connected Spaces in Admin → Federation.

sudo relaii restore BACKUP_FILE.tar.zst.enc

The command verifies the archive before replacing data. If it reports a different server identity or missing key, stop and check that you selected the correct backup. Once recovery is confirmed, take a fresh backup.

Get help with a problem

Problem	What to try
Cannot sign in	Check that you are using the correct Space address and its account details. Try password reset, or contact your Space administrator.
Missing channel	Check the selected Space and browse its public channels. For a private channel, ask a channel manager for access.
Space will not open	Check your connection. If you manage the server, run sudo relaii doctor and check DNS, ports 80/443 and the HTTPS certificate.
Invitation or reset email missing	Check the address and spam folder. Administrators should check SMTP settings and delivery logs.
Upload fails	Check the file size and your channel access. Ask an administrator to check storage limits and free space.
Messages or notifications stop arriving	Reconnect, check whether the conversation is muted, and review the app’s notification permission on your device. Ask your administrator to check the Space if the problem continues.

If you need help, contact your Space administrator with the app version, the action you tried and any error message. Administrators can use sudo relaii logs -f to follow server logs. Remove passwords, API keys and personal information before sharing logs.

Privacy and account security

Use a unique password and enable multi-factor authentication when available. Keep recovery codes somewhere you can access if you lose your authenticator. Review your signed-in devices and revoke sessions you no longer use.

Messages are encrypted in transit over HTTPS and encrypted at rest on the server. relaii does not provide end-to-end encryption. Your Space’s running server and its administrator can read messages. Ask your organisation about its access, retention and backup policies.

If you manage a Space, keep its generated keys with the database backup. Losing the message encryption key makes the saved messages unreadable; losing the federation identity can require pairing connected Spaces again.

For integration credentials, see API security.