Reticulum MeshChatX

Русский | Deutsch | Italiano | 中文 | 日本語

A extensively modified and feature-rich fork of Reticulum MeshChat by Liam Cottle.

This project is independent from the original Reticulum MeshChat project and is not affiliated with it.

• Source: git.quad4.io/RNS-Things/MeshChatX
• Releases: git.quad4.io/RNS-Things/MeshChatX/releases
• Changelog: CHANGELOG.md
• TODO: TODO.md

Important Notes

• Uses LXST
• Replaced Peewee ORM with raw SQL.

Warning

MeshChatX is not guaranteed to be wire/data compatible with older Reticulum MeshChat releases. Back up data before migration/testing.

Warning

Legacy systems are not fully supported yet. Current baseline is Python >=3.11 and Node >=24.

Demo And Screenshots

UI Previews

Requirements

• Python >=3.11 (from pyproject.toml)
• Node.js >=24 (from package.json)
• pnpm 10.32.1 (from package.json)
• Poetry (used by Taskfile.yml and CI workflows)

task install
task lint:all
task test:all
task build:all

Install Methods

Use the method that matches your environment and packaging preference.

Method	Includes frontend assets	Architectures	Best for
Docker image	Yes	linux/amd64, linux/arm64	Fastest setup on Linux servers/hosts
Python wheel (.whl)	Yes	Any Python-supported architecture	Headless/web-server install without Node build
Linux AppImage	Yes	x64, arm64	Portable desktop use
Debian package (.deb)	Yes	x64, arm64	Debian/Ubuntu installs
RPM package (.rpm)	Yes	CI-runner dependent for published artifact	Fedora/RHEL/openSUSE style systems
From source	Built locally	Host architecture	Development and custom builds

Notes:

• The release workflow explicitly builds Linux x64 and arm64 AppImage + DEB.
• RPM is also attempted by release workflow and uploaded when produced.

Quick Start: Docker

docker compose up -d

Default compose file maps:

• 127.0.0.1:8000 on host -> container port 8000
• ./meshchat-config -> /config for persistence

If your local meshchat-config permissions block writes, fix ownership:

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

Install from Release Artifacts

1) Linux AppImage (x64/arm64)

1. Download ReticulumMeshChatX-v<version>-linux-<arch>.AppImage from releases.
2. Make it executable and run:

chmod +x ./ReticulumMeshChatX-v*-linux-*.AppImage
./ReticulumMeshChatX-v*-linux-*.AppImage

2) Debian/Ubuntu .deb (x64/arm64)

1. Download ReticulumMeshChatX-v<version>-linux-<arch>.deb.
2. Install:

sudo apt install ./ReticulumMeshChatX-v*-linux-*.deb

3) RPM-based systems

1. Download ReticulumMeshChatX-v<version>-linux-<arch>.rpm if present in the release.
2. Install with your distro tool:

sudo rpm -Uvh ./ReticulumMeshChatX-v*-linux-*.rpm

4) Python wheel (.whl)

Release wheels include the built web assets.

pip install ./reticulum_meshchatx-*-py3-none-any.whl
meshchat --headless

pipx is also supported:

pipx install ./reticulum_meshchatx-*-py3-none-any.whl

Run from Source (Web Server Mode)

Use this when developing or when you need a local custom build.

git clone https://git.quad4.io/RNS-Things/MeshChatX.git
cd MeshChatX
corepack enable
pnpm install
pip install poetry
poetry install
pnpm run build-frontend
poetry run meshchat --headless --host 127.0.0.1

Run sandboxed (Linux)

To run the native meshchat binary with extra filesystem isolation, you can use Firejail or Bubblewrap (bwrap) while keeping normal network access for Reticulum and the web UI. Full examples (pip/pipx, Poetry, USB serial notes) are in:

• docs/meshchatx_linux_sandbox.md

The same page appears in the in-app Documentation list (MeshChatX docs) when served from the bundled or synced meshchatx-docs files.

Build Desktop Packages from Source

These scripts are defined in package.json and Taskfile.yml.

Linux x64 AppImage + DEB

pnpm run dist:linux-x64

Linux arm64 AppImage + DEB

pnpm run dist:linux-arm64

RPM

pnpm run dist:rpm

Or through Task:

task dist:fe:rpm

Architecture Support Summary

• Docker image: amd64, arm64
• Linux AppImage: x64, arm64
• Linux DEB: x64, arm64
• Windows: x64, arm64 (build scripts available)
• macOS: build scripts available (arm64, universal) for local build environments
• Android: build workflow and Android project are present in this repository

Android

Use the dedicated docs:

• docs/meshchatx_on_android_with_termux.md
• android/README.md

Configuration

MeshChatX supports both CLI args and env vars.

Argument	Environment Variable	Default	Description
--host	MESHCHAT_HOST	127.0.0.1	Web server bind address
--port	MESHCHAT_PORT	8000	Web server port
--no-https	MESHCHAT_NO_HTTPS	false	Disable HTTPS
--ssl-cert / --ssl-key	MESHCHAT_SSL_CERT / MESHCHAT_SSL_KEY	(none)	PEM certificate and private key paths; both must be set together. Overrides auto-generated certs under the identity ssl/ directory.
--headless	MESHCHAT_HEADLESS	false	Do not auto-launch browser
--auth	MESHCHAT_AUTH	false	Enable basic auth
--storage-dir	MESHCHAT_STORAGE_DIR	./storage	Data directory
--public-dir	MESHCHAT_PUBLIC_DIR	auto/bundled	Frontend files directory (needed for source installs without bundled assets)

Branches

Branch	Purpose
master	Stable releases. Production-ready code only.
dev	Active development. May contain breaking or incomplete changes.

Development

Common tasks from Taskfile.yml:

task install
task lint:all
task test:all
task build:all

Makefile shortcuts are also available:

Command	Description
make install	Install pnpm and poetry dependencies
make run	Run MeshChatX via poetry
make build	Build frontend
make lint	Run eslint and ruff
make test	Run frontend and backend tests
make clean	Remove build artifacts and node_modules

Versioning

Current version in this repo is 4.4.0.

• package.json is the JavaScript/Electron version source.
• meshchatx/src/version.py is synced from package.json using:

pnpm run version:sync

For release consistency, keep version fields aligned where required (package.json, pyproject.toml, meshchatx/__init__.py).

Security

Security and integrity details:

• SECURITY.md
• Built-in integrity checks and HTTPS/WSS defaults in app runtime
• CI scanning workflows in .gitea/workflows/

Adding a Language

Locale discovery is automatic. To add a new language, create a single JSON file:

1. Generate a blank template from en.json:

python scripts/generate_locale_template.py

This writes locales.json with every key set to an empty string.

2. Rename it to your language code and move it into the locales directory:

mv locales.json meshchatx/src/frontend/locales/xx.json

3. Set _languageName at the top of the file to the native name of the language (e.g. "Espanol", "Francais"). This is displayed in the language selector.

4. Translate all remaining values.

5. Run pnpm test -- tests/frontend/i18n.test.js --run to verify key parity with en.json.

No other code changes are required. The app, language selector, and tests all discover locales from the meshchatx/src/frontend/locales/ directory at build time.

Credits

• Liam Cottle - Original Reticulum MeshChat
• RFnexus - micron parser JavaScript work
• markqvist - Reticulum, LXMF, LXST