Matrix (Element) — User Guide

Electric Monk runs a Matrix homeserver (Synapse) for secure, decentralized messaging. Your Matrix ID is @you:electricmonk.io.

Features

End-to-end encrypted messaging — private conversations that even the server cannot read
Rooms and Spaces — group conversations and organizational hierarchies
Federation — communicate with users on any Matrix server (matrix.org, etc.)
Voice and video calls — 1:1 and group calls via MatrixRTC
File sharing — send files, images, and documents in conversations
Bridges — connect to other platforms (Slack, Discord, IRC, etc.) via hookshot
Web client at chat.electricmonk.io (Element Web)
Admin panel at admin.electricmonk.io
SSO login — authenticate through Authentik (same credentials as all services)

Getting Started

Web Client

Go to chat.electricmonk.io
Click Sign In
Click Continue with Authentik (SSO)
Log in with your Authentik credentials
You'll be automatically joined to the default rooms:
- #announcements:electricmonk.io
- #directory:electricmonk.io
- #general-questions:electricmonk.io

Mobile Apps (iOS / Android)

Install Element from the App Store or Google Play
Tap Sign In
Tap Edit next to the homeserver and enter: electricmonk.io
Element will discover the server via .well-known delegation
Tap Continue → Continue with Authentik
Log in with your Authentik credentials

Desktop App

Download Element Desktop from element.io/download
Click Sign In
Change the homeserver to electricmonk.io
Click Continue with Authentik and log in

How End-to-End Encryption (E2EE) Works

Matrix uses the Olm and Megolm cryptographic protocols (similar to Signal's Double Ratchet) to provide end-to-end encryption.

The Basics

Each device you log in on generates its own set of encryption keys
Messages are encrypted on your device before being sent to the server
The server stores encrypted messages — it cannot read them
Only devices with the correct keys can decrypt messages
Direct messages (DMs) and private rooms are encrypted by default

Key Concepts

Term	What It Means
Device keys	Unique cryptographic keys for each device (phone, laptop, etc.)
Session keys	Temporary keys used to encrypt messages in a specific room
Cross-signing	A way to verify all your own devices are trustworthy
Key backup	Encrypted copy of your keys stored on the server
Recovery key	A passphrase or key that unlocks your key backup
Verification	Process of confirming another user's identity via emoji or QR code

Setting Up Key Backup (Critical)

Do this immediately after your first login. Without key backup, you will permanently lose access to encrypted message history if you log out or lose a device.

After logging in, Element will prompt you to set up Secure Backup
Choose either:
- Security Key — Element generates a random recovery key (save it somewhere safe)
- Security Phrase — you choose a passphrase (must be strong and memorable)
Store your recovery key/phrase in Vaultwarden (vault.electricmonk.io)
Your message keys are now continuously backed up to the server (encrypted)

Verifying Your Devices

When you log in on a new device:

Element will show an "Verify this device" prompt on your existing device
Open Element on both devices
On the existing device, approve the new session
Compare the emoji or scan the QR code between devices
Once verified, the new device receives your message keys and can read history

If you don't have access to another logged-in device, use your recovery key or security phrase to restore your keys.

Verifying Other Users

To be certain you're talking to the real person (not an impersonator):

Open a DM with the user → click their name → Verify
Compare emoji on both sides (in person, over a phone call, etc.)
Once verified, a green shield appears next to their messages

What Happens If You Lose Your Keys

Scenario	Outcome
Lost device, key backup is set up	Restore keys on new device using recovery key/phrase
Lost device, no key backup	Permanent loss of encrypted message history
Forgot recovery key, still logged in somewhere	Create a new key backup from that device
Forgot recovery key, logged out everywhere	Previous encrypted messages are unrecoverable

Bottom line: Always set up key backup and store your recovery key in Vaultwarden.

Account Management

Your Matrix account is linked to your Authentik identity. Account settings (display name, email, password) are managed at:

account.electricmonk.io — Matrix account settings
auth.electricmonk.io — Authentik (SSO password changes)

Voice & Video Calls

Matrix supports encrypted voice and video calls via MatrixRTC:

1:1 calls: Click the phone or video icon in any DM
Group calls: Start a call from the room header in group rooms
Calls use mrtc.electricmonk.io for media relay
TURN server at turn.electricmonk.io helps with NAT traversal

Federation

Matrix is a federated protocol, meaning there is no single central server that everyone must use. Instead, thousands of independent homeservers communicate with each other, much like email — your @electricmonk.io address can message someone on @matrix.org the same way you can email anyone regardless of their provider.

How It Works

Each Matrix homeserver stores the history of the rooms its users participate in. When you send a message in a room that contains users from other servers, your homeserver forwards that message to their homeservers, and vice versa. Every server keeps its own copy of the conversation, so no single server is a point of failure.

This is fundamentally different from centralised platforms like Slack, Discord, or iMessage, where a single company controls all the data and can shut down access at any time.

What This Means for You

Talk to anyone on Matrix — you can message users on matrix.org, mozilla.org, gitter.im, or any other Matrix server. Your address is @you:electricmonk.io and it works everywhere.
Join any public room — rooms like #matrix:matrix.org or #element-web:matrix.org are hosted on other servers, but you join them from your own account with your own encryption keys.
Your data stays on your server — your account, keys, and room history live on the Electric Monk infrastructure. Other servers only see what is shared in rooms you participate in together.
No vendor lock-in — if you ever wanted to move to a different Matrix server, the protocol is open and your contacts can still reach you. Your message history in federated rooms is preserved on every participating server.

Public Room Directory

Public rooms on electricmonk.io are listed in the global Matrix room directory, meaning users on other servers can discover and join them. You can also browse rooms hosted on other servers from your own client by changing the server in the room directory search.

Troubleshooting

"Unable to decrypt" messages

Ensure key backup is set up (Settings → Security & Privacy → Secure Backup)
Try verifying the session from another logged-in device
If no other sessions exist, use your recovery key to restore

"Session not verified" warnings

Verify the new session from an existing device or using your recovery key
Go to Settings → Sessions → select the unverified session → Verify

Can't log in

Make sure the homeserver is set to electricmonk.io (not matrix.org)
Try SSO login (Continue with Authentik) rather than username/password
Verify your Authentik account is active at auth.electricmonk.io

Administration

Promoting a User to Server Admin

Because Matrix uses MAS (Matrix Authentication Service) for authentication, the traditional Synapse register_new_matrix_user command does not work. Instead, use the mas-cli tool inside the MAS container to promote an existing user to admin:

kubectl exec -it -n electricmonk deploy/ess-matrix-authentication-service -- mas-cli manage promote-admin @username:electricmonk.io

Replace @username:electricmonk.io with the full Matrix ID of the user you want to promote.

Once promoted, the user will have access to the Synapse Admin API and the Element Admin panel.