# relaii documentation for AI agents This is the Markdown edition of , written for AI agents that help people use or run relaii. It carries the same facts as that page, plus the rules an agent needs to give safe advice. For the HTTP API, read . ## What relaii is - relaii is free, self-hosted team chat. An organisation installs it on its own server. - One installation is a **Space**. It has its own address (for example `chat.example.no`), its own accounts, channels and files. - There is **no central relaii service**. `relaii.app` hosts only this website, the installer and release packages. Nobody signs in at relaii.app, and it holds no accounts, messages or support desk. - Two Spaces can be connected (federation) to share selected channels. - People use a Space in a browser at the Space address, or in the relaii apps for Apple platforms and Android. ## Rules for agents 1. **Ask for the Space address** when you need it. Never guess it, and never use `relaii.app` as a Space address. 2. **Only the Space's administrator can grant access** — reset an account, change roles, re-enable a disabled account, change server settings. If the person is not an administrator, tell them exactly what to ask for. 3. **Never ask for secrets in the conversation**: passwords, MFA codes, recovery codes, API keys, webhook URLs, backup passphrases or the contents of `/opt/relaii/.env`. Tell the person where to enter the value instead. Before logs are shared, have passwords, keys and personal data removed. 4. **Server commands change a live service.** They run on the machine that hosts the Space, as root (`sudo`). Show the command, say what it does, and recommend a backup before configuration changes or updates. 5. **`relaii restore` destroys the current database and configuration.** Do not suggest it as a troubleshooting step. Do not add `--yes` (it skips the confirmation) unless the person has explicitly asked for an unattended restore. 6. **relaii is not end-to-end encrypted.** Never claim it is. The running server and its administrator can read messages. 7. **Backups do not contain attachment files.** Whenever you discuss backups, mention that attachment storage needs its own backup. 8. **Menus differ slightly by platform and version.** Name the section (for example **Admin → API keys**) rather than inventing click paths you have not seen. ## Vocabulary | Term | Meaning | | --- | --- | | Space | One relaii installation: an address, accounts, channels and files. | | Channel | A conversation for a project or topic. Public or private. | | Direct message | A one-to-one conversation. | | Group conversation | A conversation with a small group of people, outside channels. | | Administrator | An account that can open **Admin** and manage the Space. | | Owner | The account created at setup. An administrator who can also transfer ownership and rotate the federation signing key. | | Channel manager | A channel member allowed to manage it: invite people, rename, archive or restore it, and maintain its links and widgets. Channel roles are owner, moderator, member and guest. | | Archived channel | History stays readable; nobody can post. A channel manager can restore it. | | Connected Space | Another organisation's Space paired through federation. | | Webhook | A secret URL that posts messages into one channel. | | API key | A scoped credential (`rak_…`) that lets an integration post bot messages or update widgets. | | Widget | Information embedded in a channel: data pushed by an integration, or a cached HTML page. | ## For people who use a Space ### Join an existing team 1. Open the invitation link from the administrator and create the account. 2. To sign in again, open the Space address in a browser, or enter that address in the relaii app. 3. Sign in with the account details. If asked, enter the code from the authenticator app, or a recovery code. - An account belongs to one Space. Someone in several Spaces signs in to each separately and moves between them with the Space switcher in the app. - Forgotten password: use the password reset option on the Space's sign-in page. If it is missing, or the email never arrives, the Space administrator must help. (Password reset needs email to be configured on the server.) ### Set up a Space for a team Follow the installation guide at to run relaii on your own server. Then open the new Space address, create the owner account and complete setup before inviting anyone. ### Messages, channels and files 1. Open a channel from the channel list. **Browse** lists the public channels in the Space. A private channel needs an invitation from a channel manager. 2. Write the message and send it. Use `@` to mention someone. 3. Attach a file to share it. People need access to the channel to open its files. 4. Use the message menu to edit or delete your own message, or save it for later. Available actions depend on permissions and Space settings. - Start a channel with **New channel**: enter a name and choose who can see it. If the action is missing, the administrator has limited who may create channels. - In an archived channel you can read the history but not post. Ask a channel manager to restore it. Message formatting. The syntax is closed: everything not listed here is shown as literal text, and HTML is never interpreted. | Write | Result | | --- | --- | | `**bold**` or `__bold__` | bold | | `*italic*` or `_italic_` | italic | | `++underline++` | underline | | `~~strike~~` | strikethrough | | `` `code` `` | inline code | | ```` ``` ```` on the lines before and after | code block | | `> text` | quote | | `- item` or `1. item` | list (can be nested) | | `\| a \| b \|` followed by `\| --- \| --- \|` | table | | `[label](https://example.com)` | link with a label | | `https://…` or `www.…` | link | | `@name` or `@name@server` | mention | | `#channel` | link to that channel, if the reader can see it | Only `http`, `https` and `mailto` links become clickable. ### Find a message or file Open **Search** and type words or a phrase. Combine with filters: | Filter | Finds | | --- | --- | | `from:alex` | Messages from the user `alex`. | | `in:#design` | Messages in the channel `design`. | | `after:2026-09-01` | Messages after a date. `before:` sets an upper limit. | | `has:file` | Messages with attachments. | Example: `launch in:#design has:file`. Results only include conversations the person has permission to read — a missing result may be a permission question, not a search problem. ### Shared links and widgets Open **Links & widgets** in a channel (**Content** on Android) to find shared links and embedded information. Channel managers maintain these items. To connect an external dashboard or notification service, see . ### Notifications and offline reading - Choose the notification preference in **Settings**. A single conversation can be muted, or given its own preference, without changing anything else. - In the Apple and Android apps, notification detail is set per account and per device: - **Clean** shows a general activity alert. - **Informational** includes sender and an excerpt when the app and Space support previews; otherwise it falls back to the general alert. - Offline, the Apple and Android apps show messages already downloaded to that device. Reconnect to load new messages and reply. Downloaded messages can be cleared in Settings; signing out or forgetting the account removes the local cache. ### Commands Type `/` in a conversation to see the available commands. | Command | Effect | Visible to | | --- | --- | --- | | `/help` | Shows help. | Only you | | `/mute` | Silences the conversation. | Only you | | `/unmute` | Turns its notifications back on. | Only you | | `/me action` | Sends an action message, e.g. `/me is reviewing`. | Everyone in the conversation | | `/shrug text` | Sends the text with a shrug. | Everyone in the conversation | To send a message that starts with a literal slash, begin it with `//`. ## For administrators ### Manage the Space Administrators open **Admin** to manage the Space. | Task | What to do | | --- | --- | | Invite people | Create invitations in Admin; send them by email or share the link. Check the assigned role first. | | Manage access | Review registration rules, member permissions and multi-factor authentication requirements. Disable accounts when people leave. | | Check storage | Open the storage panel for usage and upload limits. Include attachment storage in the backup plan. | | Connect another Space | Agree with the other administrator, approve the connection and choose which channels to share. Guide: . | | Add an integration | Create a webhook or API key with access to only the channels it needs. Guide: . | ### Change server configuration Installation settings live in `/opt/relaii/.env` on the server. Take a backup first, then edit and restart: ```sh sudo nano /opt/relaii/.env sudo relaii restart ``` - **Keep the domain stable.** It is the team's sign-in address and the identity that connected Spaces know. - **Never change the generated encryption and identity keys** in `.env`. Changing the message encryption key makes stored messages unreadable; changing the federation identity breaks connections to other Spaces. ### Set up invitation and password reset email Get SMTP credentials from the mail provider and set these values in `/opt/relaii/.env`. The example uses STARTTLS on port 587; use the settings the provider requires. ```sh 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 email, invitation links can still be shared by hand, but password reset emails cannot be delivered. ### Check health and version ```sh sudo relaii version sudo relaii doctor ``` `doctor` exits non-zero when something is wrong. Start every server-side investigation with these two. ### Take a backup ```sh sudo relaii backup ``` - It asks for a passphrase twice, writes an encrypted archive to `/var/lib/relaii/backups` and prints the path. - The archive has `.hmac` and `.sha256` files beside it. **Keep all three files together** when copying the backup off the server. - Store a copy off the server, and keep the passphrase separately (for example in the organisation's password manager). Without the passphrase the backup cannot be restored. - The archive contains the database, configuration, message encryption key and federation identity. **It does not contain attachment files.** Back up the local attachment storage or the S3 bucket separately — both, if both have been used. Scheduled backups: put the passphrase in a file only root can read and keep an independent copy of it. This keeps the 14 newest archives: ```sh sudo relaii backup --passphrase-file /root/.relaii-backup-pass --keep 14 ``` ### Install an update 1. Read the release notes at . 2. Choose a maintenance window and have the backup passphrase ready. 3. Run: ```sh sudo relaii update ``` relaii takes a backup before it installs anything; if that backup fails, the update stops and nothing changes. After restarting it checks the Space. When it finishes, sign in, open a conversation, send a message and open an attachment. ### Restore from a backup **Restoring replaces the current database and configuration with the backup.** Only proceed when the person has decided to restore. They need the archive with its sidecar files, the passphrase, and the matching attachment backup. 1. Prepare a relaii installation of the version recorded with the backup. Rehearse on an isolated server before a real recovery. 2. Copy the archive (with its `.hmac` and `.sha256` files) to that server and run the command below, replacing `BACKUP_FILE.tar.zst.enc` with the real path. It asks for confirmation before destroying anything and takes a safety backup of the current state first. 3. Restore the attachment storage separately. Keep a rehearsal isolated from the live Space and from connected partners. 4. Run `sudo relaii doctor`, sign in, check the message history and open an attachment. For a live recovery, also check connected Spaces in **Admin → Federation**. ```sh sudo relaii restore BACKUP_FILE.tar.zst.enc ``` The command verifies the archive before replacing data. If it reports a different server identity or a missing key, stop and check that the right backup was chosen. After a confirmed recovery, take a fresh backup. ### Server command reference | Command | What it does | | --- | --- | | `sudo relaii status` | Shows what is running. | | `sudo relaii start` / `stop` / `restart` | Starts, stops or restarts every service. | | `sudo relaii logs [service] [-f] [-n LINES]` | Shows logs; `-f` follows them. | | `sudo relaii doctor` | Checks the installation; non-zero exit if anything is wrong. | | `sudo relaii version` | Installed version, channel and latest available version. | | `sudo relaii update` | Backs up, then upgrades. `--to VERSION` picks an exact version. | | `sudo relaii backup` | Encrypted backup of database, configuration and identity. | | `sudo relaii restore FILE` | Replaces the installation's data with a backup. Destructive. | Every command accepts `--help`. The installation directory defaults to `/opt/relaii`. ## Troubleshooting | Problem | What to try | | --- | --- | | Cannot sign in | Check the Space address and that the account belongs to that Space. Try password reset, then contact the Space administrator. | | Missing channel | Check that the right Space is selected and browse its public channels. A private channel needs an invitation from a channel manager. | | Space will not open | Check the connection. On the server: `sudo relaii doctor`, then DNS, ports 80 and 443, and the HTTPS certificate. | | Invitation or reset email missing | Check the address and the spam folder. Administrators check the SMTP settings and delivery logs. | | Upload fails | Check the file size and channel access. Administrators check storage limits and free space. | | Messages or notifications stop | Reconnect, check whether the conversation is muted, and check the app's notification permission on the device. If it continues, the administrator checks the Space. | When escalating, the administrator needs the app version, what the person tried and the exact error message. Administrators follow server logs with `sudo relaii logs -f`. ## Privacy and account security - Use a unique password and enable multi-factor authentication when available. Keep recovery codes somewhere reachable if the authenticator is lost. - Review signed-in devices and revoke sessions that are no longer used. - Messages are encrypted in transit (HTTPS) and at rest on the server. **relaii does not provide end-to-end encryption.** The Space's server and administrator can read messages. Access, retention and backup policies are set by the organisation. - Administrators keep the generated keys with the database backup. Losing the message encryption key makes stored messages unreadable; losing the federation identity can mean pairing connected Spaces again. - Integration credentials (webhook URLs, API keys, session tokens): see the security section of . ## Other pages - Documentation (HTML): - API reference for agents: - Installation: - Federation guide: - Release notes: