docs/user-facing/communication-and-security/matrix.md

# Matrix: Chat, Voice & Video Calls

Welcome to **Matrix**, the primary communication platform for **The Nest**! Matrix powers our group chat rooms, direct messaging, voice channels, and video calling.

---

## 1. Getting Started & Signing In

Because Matrix is a decentralized messaging network, you will log in by connecting your client app to **The Nest's homeserver**.

### Step-by-Step Sign In:
1. Open your preferred Matrix client or visit [Element Web](https://app.element.io) in your browser.
2. Click **Sign In**, and set your homeserver address to:
   `https://starling.mynest.love`
3. Select **"Continue with sso.mynest.love/realms/nest"** when prompted.
4. You will be redirected to our standard login screen (`sso.mynest.love`) to authenticate with your passkey.
5. Once authenticated, you will be brought right back into Matrix—ready to start chatting!

> [!TIP]
> **One-Time Authentication:**
> You only need to use your passkey for initial login on a new device. Your client app will stay securely signed in until you manually log out.

---

## 2. Recommended Clients

One of the best features of Matrix is that you can choose your own application client! However, because features like video calling and screen sharing require WebRTC support, we recommend using one of the official **Element** applications:

* **Element Desktop** *(Windows, macOS, Linux)*: The recommended option for desktop users, featuring full screen-sharing and multi-party video call support.
* **Element X** *(iOS & Android)*: A modern, high-performance mobile client for chatting on the go.
* **Element Web** *(Browser)*: Accessible immediately from any modern Web browser at [app.element.io](https://app.element.io).

---

## 3. Coming from Discord? (Quick Comparison)

If you are accustomed to Discord, Matrix has a slightly different vocabulary, but the core concepts map over naturally:

| Discord Concept | Matrix Equivalent | How It Works in The Nest |
| :--- | :--- | :--- |
| **Discord Network** | **Homeserver** | The host server managing your account (ours is `starling.mynest.love`). |
| **Server** | **Space** | A folder structure used to organize multiple rooms together. Anyone can create a private or public Space. |
| **Text / Voice Channel** | **Room** | Where messaging happens! In Matrix, every room (including 1-on-1 direct messages) supports text, voice, and video. |

> [!NOTE]
> **Federation (Connecting Beyond The Nest):**
> Matrix is *federated*. This means you can use your Nest account to join public rooms or send direct messages to users on other Matrix homeservers across the internet (such as `@username:matrix.org`).

---

## 4. Voice & Video Calls

Matrix handles voice and video calls seamlessly using real-time WebRTC media streaming.

### How to Join a Call:
1. Open any Matrix room with an active discussion.
2. Click the **Call** button (phone or camera icon) in the top header.
3. The call connects automatically via `matrix-rtc.mynest.love`—no extra configuration needed!

*Screen sharing is supported when using desktop clients like **Element Desktop**.*

---

## 5. System Service Endpoints

For reference or advanced client setup, here are the service endpoints powering Matrix on The Nest:

| Service Component | URL / Endpoint | Purpose |
| :--- | :--- | :--- |
| **Homeserver (Synapse)** | `https://starling.mynest.love` | Handles chat messages and room routing |
| **Authentication Service (MAS)** | `https://mas.mynest.love` | Manages OAuth2 authentication flows |
| **Matrix RTC (LiveKit)** | `https://matrix-rtc.mynest.love` | Powers high-quality voice and video calls |

---

## 6. Troubleshooting & Related Services

* **Lost Access to Passkeys?** Contact an admin via Matrix at `@nest:starling.mynest.love` or email from your registered address to initiate account recovery.
* **Requesting Access to New Services:** Send a direct message to `@access-bot:starling.mynest.love` inside Matrix to request permissions.
* **Central Authentication:** Keycloak manages single sign-on access across Matrix and connected services.