Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Client

The Matrix Client is a bridge service that provides messaging capabilities across multiple Matrix bridges (WhatsApp, Telegram, Signal, etc.). It acts as a bridge between the Interface API and the Matrix homeserver.

Prerequisites

Before installing the Client, you’ll need to ensure you have the required dependencies and external services.

System requirements

The Client requires:

  • Go 1.24.0 or higher - The Go programming language runtime and compiler
  • libolm - Cryptographic library for Matrix end-to-end encryption
  • RabbitMQ - Message broker for background workers
  • Swagger - API documentation tool

Installing dependencies

Debian/Ubuntu

Install the required system dependencies:

sudo apt-get update
sudo apt-get install -y \
  golang-1.24 \
  libolm-dev \
  build-essential

If your distribution doesn’t have Go 1.24 in the default repositories, download it from go.dev/dl:

wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

Install Swagger:

go install github.com/swaggo/swag/cmd/swag@latest
go get github.com/swaggo/http-swagger
go get github.com/swaggo/files
export PATH=$PATH:$(go env GOPATH)/bin

macOS

For macOS (especially M-series):

brew install libolm
export LIBRARY_PATH="/opt/homebrew/lib:$LIBRARY_PATH"
export CPATH="/opt/homebrew/include:$CPATH"
export CGO_CFLAGS="-I/opt/homebrew/include"
export CGO_LDFLAGS="-L/opt/homebrew/lib"

Install RabbitMQ:

External services

The Client requires the following external services to be running:

Matrix Homeserver

A running Matrix homeserver (e.g., Synapse) is required. See the Synapse setup guide for instructions on setting up a Matrix homeserver.

Matrix Authentication Service (MAS)

MAS provides OAuth2/OIDC authentication for Matrix. You must configure and run MAS before starting the Client. See the Matrix Client MAS setup guide for detailed instructions.

Matrix Bridges

Configure the bridges you want to support on your homeserver. Supported bridges include:

  • WhatsApp (mautrix-whatsapp)
  • Telegram (mautrix-telegram)
  • Signal (mautrix-signal)
  • Instagram (mautrix-instagram)
  • iMessage (mautrix-imessage)
  • Facebook (mautrix-facebook)

Important

Configure self-signing in each bridge to avoid encryption errors:

# bridge.conf file
encryption:
  self_sign: true

For Signal bridge, ensure your homeserver is configured to put phone numbers in topic:

network:
  in_topics: true

Quick setup

The quickest way to get started is to clone the repository and configure the service manually.

Clone the repository

git clone https://github.com/shortmesh/Client.git
cd Client

Create configuration

Create your configuration file from the example:

cp conf.yaml.example conf.yaml

Configure settings

Edit conf.yaml with your Matrix homeserver and MAS credentials:

# Matrix homeserver URL
homeserver: https://matrix.example.com

# Matrix homeserver domain
homeserver_domain: example.com

# MAS OAuth credentials
mas_client_id: your-mas-client-id
mas_client_secret: your-mas-client-secret

# Database encryption key (high entropy string)
# Generate with: openssl rand -hex 32
db_key: your-64-char-hex-key

# RabbitMQ connection
rabbitmq_url: amqp://guest:guest@localhost:5672/

# API configuration
api:
  host: 0.0.0.0
  port: 8080

The client will create rooms and synchronize for your users for every bridge configured in conf.yaml.

Generate Swagger documentation

swag init

Install Go dependencies

go mod tidy

Start the server

go run .

The server will start and listen on http://localhost:8080.

Verify the installation

Once running, verify everything is working:

# View Swagger documentation in browser
open http://localhost:8080/docs/index.html

Docker

Docker provides an isolated environment and simplifies dependency management.

Prerequisites

Ensure you have Docker installed:

# Verify Docker installation
docker --version

Create configuration

Before building the Docker image, you need a conf.yaml file:

cp conf.yaml.example conf.yaml
# Edit conf.yaml with your configuration

Build the image

Build the Docker image:

docker build -t matrix-client .

Run the container

Start the client service:

docker run -d \
  --name matrix-client \
  -p 8080:8080 \
  -v $(pwd)/db:/app/db \
  -v $(pwd)/downloads:/app/downloads \
  -v $(pwd)/conf.yaml:/app/conf.yaml \
  matrix-client

View logs

docker logs -f matrix-client

Stop the container

docker stop matrix-client
docker rm matrix-client

Docker Compose

Docker Compose orchestrates the Client with RabbitMQ. This is the recommended approach for production deployments.

Create docker-compose.yml

Create a docker-compose.yml file in your project directory:

version: '3.8'

services:
  rabbitmq:
    image: rabbitmq:3-management-alpine
    container_name: matrix-rabbitmq
    ports:
      - "5672:5672"
      - "15672:15672"
    environment:
      RABBITMQ_DEFAULT_USER: guest
      RABBITMQ_DEFAULT_PASS: guest
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
    restart: unless-stopped

  matrix-client:
    build: .
    container_name: matrix-client
    ports:
      - "8080:8080"
    volumes:
      - ./db:/app/db
      - ./downloads:/app/downloads
      - ./conf.yaml:/app/conf.yaml
    environment:
      - HOST=0.0.0.0
      - PORT=8080
    depends_on:
      - rabbitmq
    restart: unless-stopped

volumes:
  rabbitmq_data:

Start all services

docker compose up -d

This will start:

  • RabbitMQ message broker with management UI
  • Matrix Client service

View logs

# All services
docker compose logs -f

# Client logs only
docker compose logs -f matrix-client

Access services

Stop services

# Stop all services
docker compose down

# Stop and remove volumes
docker compose down -v

Rebuild after changes

docker compose up -d --build

Systemd service

For production Linux deployments, running the Client as a systemd service provides automatic startup, restart on failure, and integration with system logging.

Create service file

Create /etc/systemd/system/matrix-client.service:

[Unit]
Description=ShortMesh Matrix Client
After=network.target rabbitmq-server.service
Wants=rabbitmq-server.service

[Service]
Type=simple
User=shortmesh
Group=shortmesh
WorkingDirectory=/opt/matrix-client
ExecStart=/opt/matrix-client/matrix-client
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Manual setup

1. Build the binary

go build -o matrix-client .

2. Create installation directory

sudo mkdir -p /opt/matrix-client
sudo cp matrix-client conf.yaml /opt/matrix-client/
sudo mkdir -p /opt/matrix-client/db
sudo mkdir -p /opt/matrix-client/downloads

3. Create dedicated user

sudo useradd --system --user-group shortmesh
sudo chown -R shortmesh:shortmesh /opt/matrix-client

4. Install systemd service

sudo cp matrix-client.service /etc/systemd/system/
sudo systemctl daemon-reload

5. Enable and start

sudo systemctl enable matrix-client
sudo systemctl start matrix-client

Managing the service

Once installed, manage the service with standard systemd commands:

# Start the service
sudo systemctl start matrix-client

# Stop the service
sudo systemctl stop matrix-client

# Restart the service
sudo systemctl restart matrix-client

# View status
sudo systemctl status matrix-client

# View logs
sudo journalctl -u matrix-client -f

# View logs since last boot
sudo journalctl -u matrix-client -b

# Enable auto-start on boot
sudo systemctl enable matrix-client

# Disable auto-start
sudo systemctl disable matrix-client

Configuration reference

This section provides a complete reference for all configuration options available in the conf.yaml file.

Server configuration

# Matrix homeserver URL
homeserver: https://matrix.example.com

# Matrix homeserver domain
homeserver_domain: example.com

# API server configuration
api:
  host: 0.0.0.0
  port: 8080

Authentication

# MAS OAuth credentials
mas_client_id: your-mas-client-id
mas_client_secret: your-mas-client-secret

Database

# Database encryption key (high entropy string)
# Generate with: openssl rand -hex 32
# IMPORTANT: Never change this key after initial setup
db_key: your-64-char-hex-key

RabbitMQ

# RabbitMQ connection URL
rabbitmq_url: amqp://guest:guest@localhost:5672/

For production, use authenticated connections:

rabbitmq_url: amqp://username:password@rabbitmq-host:5672/

Bridges

Configure the bridges supported by your homeserver:

Message queues

The Client uses RabbitMQ for message routing and device management.

Adding devices queue

Incoming requests for adding devices are routed to:

exchange: "bridges.topic"
binding_key: "bridges.topic.add_new_device"
queue_name: {username}_add_new_device

Incoming messages queue

Incoming messages from bridges are routed to:

exchange: "contacts.topic"
binding_key: "contacts.topic.incoming_messages"
queue_name: {username}_incoming_messages

Message payload structure

Text and media messages follow this structure:

{
  "IsContact": true,
  "Type": "text",
  "From": "+1234567890",
  "To": "+0987654321",
  "Text": "Message content",
  "Media": {
    "Content": "base64_encoded_bytes",
    "Info": {
      "Size": 1024.5,
      "MimeType": "image/jpeg",
      "Width": 1920,
      "Height": 1080,
      "BlurHash": "LKO2?U%2Tw=w]~RBVZRi};RPxuwH"
    }
  }
}

API documentation

The Client provides interactive API documentation through Swagger UI. Access it at:

http://localhost:8080/docs/index.html

The Swagger UI allows you to:

  • Browse all available endpoints
  • View request and response schemas
  • Test API calls directly from your browser
  • See example payloads

To regenerate the Swagger documentation after code changes:

swag init

Reverse proxy configuration

For production deployments, use a reverse proxy like Nginx to handle TLS termination and route requests.

Nginx configuration with MAS

Example Nginx configuration that routes both MAS and Synapse:

server {
    listen 443 ssl http2;
    server_name matrix.example.com;

    ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;

    client_max_body_size 50M;

    # IMPORTANT: MAS SHOULD COME BEFORE SYNAPSE FOR REGEX NGINX REASONS

    # MAS-backed client auth routes
    location ~ ^/_matrix/client/(v3|v1)/(login|logout|refresh|auth_metadata|capabilities) {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Synapse endpoints
    location ~ ^(/_matrix|/_synapse/client|/_synapse/mas) {
        proxy_pass http://127.0.0.1:8008;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # .well-known
    location /.well-known/matrix/ {
        alias /var/www/matrix/.well-known/matrix/;
        default_type application/json;
        add_header Access-Control-Allow-Origin *;
    }
}

.well-known/matrix/client

{
  "m.homeserver": {
    "base_url": "https://matrix.example.com"
  },
  "org.matrix.msc2965.authentication": {
    "issuer": "https://auth.example.com/",
    "account": "https://auth.example.com/account/"
  }
}

Matrix Authentication Service (MAS)

MAS is required for OAuth2/OIDC authentication with Matrix.

Docker setup

Example Docker Compose configuration for MAS:

services:
  matrix-auth-service:
    image: ghcr.io/element-hq/matrix-authentication-service:latest
    container_name: matrix-auth-service
    environment:
      - MAS_CONFIG=/app/config/config.yaml
    ports:
      - "8080:8080"
      - "8081:8081" # health endpoint
    volumes:
      - ./config.yaml:/app/config/config.yaml:ro
    restart: unless-stopped
    network_mode: "host"

MAS configuration

Example config.yaml for MAS:

http:
  listeners:
  - name: web
    resources:
    - name: discovery
    - name: human
    - name: oauth
    - name: compat
    - name: graphql
    - name: assets
    binds:
      - host: 0.0.0.0
        port: 8080
    proxy_protocol: false
  - name: internal
    resources:
    - name: health
    binds:
    - host: localhost
      port: 8081
    proxy_protocol: false
  trusted_proxies:
  - 192.168.0.0/16
  - 172.16.0.0/12
  - 10.0.0.0/10
  - 127.0.0.1/8
  - fd00::/8
  - ::1/128
  public_base: https://auth.example.com/
  issuer: https://auth.example.com/

matrix:
  kind: synapse
  homeserver: matrix.example.com
  endpoint: https://matrix.example.com/
  secret: your-shared-secret-from-synapse-config

account:
  password_registration_enabled: true
  password_recovery_enabled: true
  account_deactivation_allowed: true
  login_with_email_allowed: true

For detailed MAS setup instructions, see this guide.

Security considerations

Key management

Never share or commit these sensitive values to version control:

  • db_key
  • mas_client_secret

Never change the db_key after initial deployment as it will make the database unreadable.

Additional resources