MMRelay

(Meshtastic <=> Matrix Relay)

A powerful and easy-to-use relay between Meshtastic devices and Matrix chat rooms, allowing seamless communication across platforms. This opens the door for bridging Meshtastic devices to many other platforms.

Features

• Bidirectional message relay between Meshtastic devices and Matrix chat rooms, capable of supporting multiple meshnets
• Supports serial, network, and BLE connections for Meshtastic devices
• Custom fields are embedded in Matrix messages for relaying messages between multiple meshnets
• Truncates long messages to fit within Meshtastic's payload size
• SQLite database to store node information for improved functionality
• Customizable logging level for easy debugging
• Configurable through a simple YAML file
• Supports mapping multiple rooms and channels 1:1
• Relays messages to/from an MQTT broker, if configured in the Meshtastic firmware
• Bidirectional replies and reactions support
• Native Docker support
• Supports encrypted Matrix rooms 🔐 (Matrix E2EE)
• Unified directory structure 📁 (New in v1.3)

Encryption note: MMRelay supports encrypted Matrix rooms (Matrix E2EE). For details on how this works and its security implications, see the E2EE Setup Guide.

Improved BLE stability (v1.3.3): The Meshtastic Python library has been replaced with mtjk, a fork with BLE reliability improvements (auto-reconnection, state management, notification recovery) along with thread-safety and connection handling fixes. Changes may be upstreamed selectively once they've been battle-tested here. See the Refactor Program for scope and rationale.

Documentation

MMRelay supports multiple deployment methods including pip/pipx, Docker, and Kubernetes. For complete setup instructions and all deployment options, see:

• Installation Instructions - Setup and configuration guide
• What's New in v1.3 - Latest release changes and migration info
• Migration Guide for v1.3 - Upgrading from v1.2 or earlier
• Docker Guide - Docker deployment methods
• Kubernetes Guide - Kubernetes deployment guide
• E2EE Setup Guide - Matrix End-to-End Encryption configuration

---

Plugins

MMRelay supports plugins for extending its functionality, enabling customization and enhancement of the relay to suit specific needs.

Core Plugins

Generate a map of your nodes:

Produce high-level details about your mesh:

See the full list of core plugins.

Plugin System

MMRelay supports three plugin types:

• Core Plugins: Built in with MMRelay
• Community Plugins: Git-based plugins that MMRelay syncs for you
• Custom Plugins: Local/manual plugins for private use and development

MMRelay manages plugin directories under MMRELAY_HOME (default ~/.mmrelay). Most users only need config.yaml; path details matter mainly when authoring custom plugins.

Check the Community Plugins Development Guide in our wiki to get started.

✨️ Visit the Community Plugins List!

Install a Community Plugin

Add the repository under the community-plugins section in config.yaml:

community-plugins:
  example-plugin:
    active: true
    repository: https://github.com/jeremiah-k/mmr-plugin-template.git
    commit: 0123456789abcdef0123456789abcdef01234567
    install_requirements: true

• Community plugins run in the same MMRelay process and inherit its permissions. Use trusted sources.
• Dependency installation is per-plugin and defaults to off (install_requirements: false).
• Prefer commit-pinned refs.
• Explicit branch and tag refs are allowed for dependency install, but MMRelay logs warnings.
• Missing ref (implicit default branch) is not eligible for dependency install.
• Dependencies install once per resolved local commit and are skipped when unchanged.

---

Getting Started with Matrix

See our Wiki page Getting Started With Matrix & MMRelay.

---

Already on Matrix?

Join us!

• Our project's room: #mmrelay:matrix.org
• Part of the Meshnet Club Matrix space: #meshnetclub:matrix.org
• Public Relay Room: #mmrelay-relay-room:matrix.org - Where we bridge multiple meshnets. Feel free to join us, with or without a relay!