Reticulum MeshChatX

Todo - Website (Soon)

Warning

Backup your reticulum-meshchat folder before using! MeshChatX will attempt to auto-migrate whatever it can from the old database without breaking things, but it is best to keep backups.

Contact me for any issues or ideas:

LXMF: 7cc8d66b4f6a0e0e49d34af7f6077b5a

A Reticulum MeshChat fork from the future.

This project is separate from the original Reticulum MeshChat project, and is not affiliated with the original project.

Goal

To provide everything you need for Reticulum, LXMF, and LXST in one beautiful and feature-rich application.

• Desktop app (Linux, Windows, macOS)
• Self-host on your server easily with or without containers
• Mobile support (Android)
• Reliable, secure, fast and easy to use.

Note on macOS: You will need to manually build or use containers since I do not have a macOS machine or runner.

Quick Start (Docker - Recommended)

The easiest way to get MeshChatX running is using Docker. Our official image is multi-arch and supports linux/amd64 and linux/arm64 (Raspberry Pi, etc.).

# Pull and run the latest image
docker pull git.quad4.io/rns-things/meshchatx:latest

# Run MeshChatX using Docker Compose (Recommended)
# This will create a meshchat-config directory for persistence
docker compose up -d

Docker Permissions Note

If you encounter a PermissionError when running the Docker container, it's likely because the container's user (UID 1000) doesn't have permission to write to your host's ./meshchat-config folder. You can fix this by running:

sudo chown -R 1000:1000 ./meshchat-config

Check releases for pre-built binaries (AppImage, DEB, EXE) if you prefer standalone apps. (coming soon)

Installation via Wheel (.whl)

The simplest way to install MeshChatX on most systems is using the pre-built wheel from our releases. This package bundles the built frontend, so you don't need to deal with Node.js or building assets yourself. No Electron needed, it is a webserver basically, so you use your browser to access it.

1. Install directly from the release:

   pip install https://git.quad4.io/RNS-Things/MeshChatX/releases/download/v4.1.0/reticulum_meshchatx-4.1.0-py3-none-any.whl
   
   # pipx
   pipx install https://git.quad4.io/RNS-Things/MeshChatX/releases/download/v4.1.0/reticulum_meshchatx-4.1.0-py3-none-any.whl
   

2. Run MeshChatX:

   meshchat --headless
   

Major Features

• Full LXST Support: Custom voicemail, phonebook, contact sharing, and ringtone support.
• Interface Discovery and auto-connecting - Discover interfaces, auto-connect or connect to trusted ones, map them all!
• Multi-Identity: Switch between multiple Reticulum identities seamlessly.
• Modern UI/UX: A completely redesigned, intuitive interface.
• Integrated Maps: OpenLayers with MBTiles support for offline maps.
• Security: Read more about it in the Security section.
• Offline Docs: Access Reticulum documentation without an internet connection.
• Expanded Tools: Includes dozens of more tools.
• Page Archiving: Built-in crawler and browser for archived pages offline.
• Banishment: Banish LXMF users, Telephony, and NomadNet Nodes.
• i18n: Support for English, German, Italian, and Russian.
• Advanced Diagnostic Engine: Mathematically grounded crash recovery using Active Inference and Information Theory.

Screenshots

Telephony & Calling

Phone

Active Call

Call Ended

Voicemail

Ringtone Settings

Networking & Visualization

Network Visualiser

Page Archives

Archives Browser

Viewing Archived Page

Tools & Identities

Tools

Identity Management

Pipx / Global Installation

If you prefer to install MeshChatX globally using pipx, pip or uv, you can do so directly from the repository. However, you must specify the path to your built frontend files using the --public-dir flag or MESHCHAT_PUBLIC_DIR environment variable, as the static files are not bundled with the source code. The release .whl packages include the built frontend files and also there is a seperate frontend zip to grab and use.

1. Install MeshChatX:

   pipx install git+https://git.quad4.io/RNS-Things/MeshChatX
   

2. Run with Frontend Path:

   # Replace /path/to/MeshChatX/meshchatx/public with your actual path
   meshchat --public-dir /path/to/MeshChatX/meshchatx/public
   

Manual Installation (From Source)

If you want to run MeshChatX from the source code locally:

1. Clone the repository:

   git clone https://git.quad4.io/RNS-Things/MeshChatX
   cd MeshChatX
   

2. Build the Frontend: Requires Node.js and pnpm.

   corepack enable
   pnpm install
   pnpm run build-frontend
   

3. Install & Run Backend: Requires Python 3.10+ and Poetry.

   pip install poetry
   poetry install
   poetry run meshchat --headless --host 127.0.0.1
   

Cross-Platform Building (Linux to Windows)

If you are on Linux and want to build the Windows .exe and installer locally, you can use Wine.

1. Install Windows Python and Git inside Wine:

   # Download Python installer
   wget https://www.python.org/ftp/python/3.13.1/python-3.13.1-amd64.exe
   # Install Python to a specific path
   wine python-3.13.1-amd64.exe /quiet InstallAllUsers=1 TargetDir=C:\Python313 PrependPath=1
   
   # Download Git installer
   wget https://github.com/git-for-windows/git/releases/download/v2.52.0.windows.1/Git-2.52.0-64-bit.exe
   # Install Git (quietly)
   wine Git-2.52.0-64-bit.exe /VERYSILENT /NORESTART
   

2. Install Build Dependencies in Wine:

   wine C:/Python313/python.exe -m pip install cx_Freeze poetry
   wine C:/Python313/python.exe -m pip install -r requirements.txt
   

3. Run the Build Task:

   # Build only the Windows portable exe
   WINE_PYTHON="wine C:/Python313/python.exe" task dist:win:wine
   
   # Or build everything (Linux + Windows) at once
   WINE_PYTHON="wine C:/Python313/python.exe" task dist:all:wine
   

Configuration

MeshChatX can be configured via command-line arguments or environment variables.

Argument	Environment Variable	Default	Description
--host	MESHCHAT_HOST	127.0.0.1	Web server address
--port	MESHCHAT_PORT	8000	Web server port
--no-https	MESHCHAT_NO_HTTPS	false	Disable HTTPS
--headless	MESHCHAT_HEADLESS	false	Don't launch browser
--auth	MESHCHAT_AUTH	false	Enable basic auth
--storage-dir	MESHCHAT_STORAGE_DIR	./storage	Data directory
--public-dir	MESHCHAT_PUBLIC_DIR	-	Frontend files path

Development

We use Task for automation.

Task	Description
task install	Install all dependencies
task run	Run the application
task dev	Run the application in development mode
task lint:all	Run all linters (Python & Frontend)
task lint:be	Lint Python code only
task lint:fe	Lint frontend code only
task fmt:all	Format all code (Python & Frontend)
task fmt:be	Format Python code only
task fmt:fe	Format frontend code only
task test:all	Run all tests
task test:cov	Run tests with coverage reports
task test:be	Run Python tests only
task test:fe	Run frontend tests only
task build:all	Build frontend and backend
task build:fe	Build only the frontend
task build:wheel	Build Python wheel package
task compile	Compile Python code to check for syntax errors
task docker:build	Build Docker image using buildx
task docker:run	Run Docker container using docker-compose
task dist:linux:appimage	Build Linux AppImage
task dist:win:exe	Build Windows portable executable
task dist:win:wine	Build Windows portable (Wine cross-build)
task dist:all	Build all Electron apps
task dist:all:wine	Build all Electron apps (Wine cross-build)
task android:prepare	Prepare Android build
task android:build	Build Android APK
task dist:fe:flatpak	Build Flatpak package
task clean	Clean build artifacts and dependencies

Security

• ASAR Integrity (Stable as of Electron 39)
• Built-in automatic integrity checks on all files (frontend and backend)
• HTTPS by default (automated locally generated certs)

• Layered CSP Protection: 3-layer Content Security Policy (Backend, Electron Session, and Loading Screen) to prevent XSS and unauthorized resource loading.

• Redundant CORS protection (loading.html, python backend server, electron main.js)
• Updated dependencies and daily scanning (OSV)
• Comprehensive Scanning Pipeline: Integrated Trivy for filesystem and container image scanning, alongside OSV-Scanner for vulnerability tracking.
• SBOM for dependency observability and tracking
• Extensive testing and fuzzing (Property-based testing with Hypothesis).
• Rootless docker images
• Pinned actions and container images (supply chain security and deterministic builds)

Advanced Diagnostic Engine

MeshChatX includes a uniquely sophisticated crash recovery system designed for the unpredictable hardware environments.

• Probabilistic Active Inference: Uses Bayesian-inspired heuristics to determine root causes (e.g., OOM, RNS config issues, LXMF storage failures) with up to 99% confidence.
• Mathematical Grounding: Quantifies system instability using Shannon Entropy and KL-Divergence, providing a numerical "disorder index" at the time of failure.
• Manifold Mapping: Identifies "Failure Manifolds" across the entire vertical stack from Kernel and Python versions to RNS interface state and LXMF database integrity.

All running locally on your own hardware and it might not be perfect, but it will only get better. The idea is to provide you the help to possibly fix it when you cannot reach me.

Credits

• Liam Cottle - Original Reticulum MeshChat
• RFnexus - micron-parser-js
• Marqvist - Reticulum, LXMF, LXST