Element

Element is a secure, decentralized communication app built on the Matrix protocol.

What it is

Element (formerly Riot) is the flagship client for the Matrix protocol, providing a user-friendly interface for end-to-end encrypted messaging, voice, and video calls. It operates in a decentralized manner, meaning users can choose their own "homeserver" while still communicating with users on other servers.

What problem it solves

It solves the problem of "walled gardens" in communication (like WhatsApp or Slack) by using an open standard. It provides sovereign control over data without sacrificing modern features like multi-device sync, rich media sharing, and integrations.

Where it fits in the stack

Element sits in the Communication and Collaboration layer. It serves as the primary interface for both human-to-human communication and bot-to-human notifications within a self-hosted ecosystem.

Typical use cases

• Personal Messaging: Secure, E2EE alternative to commercial messaging apps.
• Team Collaboration: Organizing projects and discussions into "Spaces" and "Rooms".
• Home Automation Notifications: Receiving alerts from services like Home Assistant or custom scripts.
• Bridging: Acting as a unified interface for Discord, Telegram, and Slack via Matrix bridges.

Strengths

• Sovereignty: Full control over your data when self-hosted.
• E2EE: High-grade end-to-end encryption for all conversations.
• Extensibility: Powerful API and "Widget" system for custom integrations.
• Open Standard: Interoperable with any other Matrix client or server.
• Matrix 1.18+ Safety: Enhanced trust and safety features including Policy Servers and granular invite blocking.

Limitations

• UX Complexity: The decentralized nature (homeservers, cross-signing) can be confusing for new users compared to centralized apps.
• Resource Intensive: Running a full Matrix homeserver (Synapse) can be resource-heavy for low-end hardware.
• Storage Growth: Encrypted history and media can grow significantly over time without proper cleanup policies.

When to use it

• When you need secure, encrypted communication that you fully control.
• When you want to bridge multiple messaging platforms (Discord, Telegram, Slack) into a single client.
• When you need a reliable notification channel for your home automation system.

When not to use it

Do not use Element as a drop-in replacement for simple SMS-style family messaging if users are not ready to understand homeservers, key backup, and device verification. For large regulated organizations, validate Matrix retention, moderation, discovery, and e-discovery requirements before replacing Slack or Microsoft Teams.

Getting started

Web/Desktop App

The easiest way to start is by using the hosted version or the desktop client: 1. Download Element from element.io. 2. Create an account on the default matrix.org server or specify your own.

Docker (Self-Hosted Web Client)

To host the Element web interface yourself (requires a separate homeserver like Synapse). As of May 2026, ensure you use the latest stable branch for Matrix 1.18+ compatibility.

services:
  element:
    image: vectorim/element-web:latest
    ports:
      - "8080:80"
    restart: always
    environment:
      - ELEMENT_DEFAULT_HS_URL=https://matrix.example.com

Matrix RTC SFU (Video Calls)

For high-performance video conferencing in Element, a Selective Forwarding Unit (SFU) is recommended:

services:
  matrix-rtc-sfu:
    image: ghcr.io/element-hq/matrix-rtc-sfu:latest
    ports:
      - "8090:8090"
    environment:
      - SFU_EXTERNAL_URL=https://sfu.example.com

CLI examples

While Element is a GUI, the Matrix ecosystem provides CLI tools like matrix-commander for automation:

# Install the CLI in an isolated Python environment
python3 -m pip install --user matrix-commander

# Log in interactively and store credentials for later commands
matrix-commander --login password

# Send a message using exported room configuration
: "${MATRIX_ROOM_ID:?set MATRIX_ROOM_ID to a Matrix room ID}"
matrix-commander --room "$MATRIX_ROOM_ID" --message "Hello from the home-office automation stack"

# Get room info for the same configured room
matrix-commander --room "$MATRIX_ROOM_ID" --room-info

API examples

The Matrix Client-Server API allows direct programmatic interaction. The examples below are runnable after exporting real credentials from a bot or test account.

Python (using matrix-nio)

import asyncio
import os
from nio import AsyncClient

HOMESERVER = os.environ["MATRIX_HOMESERVER"]
USER_ID = os.environ["MATRIX_USER_ID"]
PASSWORD = os.environ["MATRIX_PASSWORD"]
ROOM_ID = os.environ["MATRIX_ROOM_ID"]

async def main():
    client = AsyncClient(HOMESERVER, USER_ID)
    login_response = await client.login(PASSWORD)
    if getattr(login_response, "access_token", None) is None:
        raise RuntimeError(f"Matrix login failed: {login_response}")

    # Send a standard message
    await client.room_send(
        room_id=ROOM_ID,
        message_type="m.room.message",
        content={
            "msgtype": "m.text",
            "body": "Alert: Motion detected in the garden!"
        },
    )

    # Advanced: Update room topic (State Event)
    # Requires sufficient power level in the room
    await client.room_put_state(
        room_id=ROOM_ID,
        event_type="m.room.topic",
        content={"topic": "Garden Status: Active Alerts"},
    )

    # Advanced: Send a custom state event for automation tracking
    await client.room_put_state(
        room_id=ROOM_ID,
        event_type="com.homelab.sensor_state",
        state_key="garden_motion",
        content={
            "status": "alerting",
            "last_seen": "2026-05-13T12:00:00Z"
        }
    )

    await client.close()

asyncio.run(main())

Curl example

: "${MATRIX_HOMESERVER:=https://matrix.org}"
: "${MATRIX_ROOM_ID:?set MATRIX_ROOM_ID to a Matrix room ID}"
: "${MATRIX_ACCESS_TOKEN:?set MATRIX_ACCESS_TOKEN to a bot or user access token}"

curl -X POST \
  -H "Authorization: Bearer $MATRIX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"m.text","body":"Hello from curl"}' \
  "$MATRIX_HOMESERVER/_matrix/client/v3/rooms/$MATRIX_ROOM_ID/send/m.room.message/$(date +%s)"

Related tools / concepts

• Synapse — The most common Matrix homeserver (v1.153.0+).
• Dendrite — A next-generation, high-performance Matrix homeserver.
• Home Assistant — Frequently integrated with Element for notifications.
• Authentik — Used for SSO authentication into Element/Matrix.
• Bridges — Connect Matrix to other services like Telegram and Discord.
• Nextcloud — For file storage and cloud services alongside communication.
• Gitea — For hosting code and triggering notifications to Element.
• Paperless-ngx — For notifying users when new documents are indexed.
• SearXNG — For secure search results sharing within Element rooms.
• Vikunja — For task management notifications and team coordination.
• Element X — Successor mobile clients built with the Matrix Rust SDK for extreme performance.

Links

• Official Website
• GitHub Repository
• Matrix Protocol
• Matrix v1.18 Spec

Backlog

• [x] Perform quarterly technical freshness audit (May 2026).

Contribution Metadata

• Confidence: high
• Last reviewed: 2026-05-26

Sources / References

• https://element.io/
• https://github.com/vector-im/element-web
• https://matrix.org/docs/api/client-server/
• https://github.com/8go/matrix-commander
• https://matrix.org/blog/2026/03/26/matrix-v1.18-release/