Meshy

Ruff

Meshy is a GTK4/libadwaita client for MeshCore. The goal is to provide the best Linux experience.

The app is already fairly feature complete and stable, but note it is still in active development, so things may still significantly change. Feedback with missing features, ideas and bugs is welcome.

Installation

Flathub

flatpak install flathub page.codeberg.sesivany.Meshy

Meshy Flatpak repo

1. Add the repo:

flatpak remote-add --if-not-exists meshy https://meshy-app.org/meshy.flatpakrepo

2. Install Meshy:

flatpak install meshy page.codeberg.sesivany.Meshy

To install the development version (latest from main branch) instead:

flatpak install meshy page.codeberg.sesivany.Meshy//master

AppImage

The AppImage format is not officially supported. It is provided 'as is' and with no support.

Download the latest AppImage from, make it executable and run:

chmod +x Meshy.AppImage
./Meshy.AppImage

Building from source

Flatpak

Install flatpak-builder and the GNOME SDK:

flatpak install flathub org.gnome.Sdk//50 org.gnome.Platform//50

Build and install:

flatpak-builder --force-clean --user --install builddir page.codeberg.sesivany.Meshy.json

Or to create a .flatpak bundle:

flatpak-builder --force-clean --repo=repo builddir page.codeberg.sesivany.Meshy.json
flatpak build-bundle repo meshy.flatpak page.codeberg.sesivany.Meshy master

All dependencies (including third-party Python packages and native libraries) are handled by the Flatpak manifest automatically.

AppImage

Meshy also includes a local AppImage build path intended for packaging tests and release automation.

Build dependencies are the same as the native build, plus:

• linuxdeploy (required for AppImage bundling; the script can download it automatically)
• curl or wget if you want the script to download missing AppImage tools automatically

Build a local AppImage:

uv run ./build-aux/appimage/build-appimage.sh --download-tools

This is the normal full build path. It writes a staged AppDir and the final AppImage to dist/.

If linuxdeploy is already installed on your machine, you can skip the download step:

uv run ./build-aux/appimage/build-appimage.sh

When the script downloads linuxdeploy as an AppImage, it runs it with APPIMAGE_EXTRACT_AND_RUN=1 so CI and other FUSE-less environments do not need /dev/fuse.

The final artifact is dist/Meshy.AppImage.

Useful variants:

# Stop after producing dist/AppDir for inspection
uv run ./build-aux/appimage/build-appimage.sh --appdir-only --download-tools
# Build an AppImage without QR scanner support
uv run ./build-aux/appimage/build-appimage.sh --download-tools --no-qr

The generated AppImage uses the same packaging flow that CI uses, so local runs exercise the release path directly.

Native build

Dependencies

Build dependencies:

• meson (>= 0.62.0)
• ninja
• python3
• glib2 (gio-2.0, glib-compile-resources, glib-compile-schemas)
• gtk4 (gtk4-update-icon-cache)
• desktop-file-utils (desktop-file-validate)
• appstream (appstreamcli)
• gettext (msgfmt)

Runtime dependencies:

• gtk4
• libadwaita
• gstreamer
• libshumate
• geoclue2
• zbar (optional, for QR code scanning)
• python3-gobject (PyGObject)
• python3-pycryptodome (pip: pycryptodome)
• python3-pyzbar (pip: pyzbar) (optional, for QR code scanning)
• python3-pyserial
• python3-segno (pip: segno)

On Fedora:

sudo dnf install meson ninja-build python3 glib2-devel gtk4-devel libadwaita-devel \
 gstreamer1-devel libshumate-devel geoclue2-devel zbar-devel \
 python3-gobject python3-pyserial desktop-file-utils appstream gettext
pip install pycryptodome pyzbar segno

On Debian/Ubuntu:

sudo apt install meson ninja-build python3 libglib2.0-dev libgtk-4-dev libadwaita-1-dev \
 libgstreamer1.0-dev libshumate-dev libzbar-dev \
 python3-gi python3-pycryptodome python3-pyzbar python3-serial python3-segno \
 desktop-file-utils appstream gettext

Build options

To build without QR code scanning (e.g. if zbar or pyzbar are not available on your distribution):

meson setup builddir --prefix=/usr -Dqr_scanner=false

The "Scan QR Code" option will be hidden from the UI when built without this feature.

To build without the keyboard shortcuts dialog (e.g. on systems with libadwaita < 1.8 such as Debian Stable):

meson setup builddir --prefix=/usr -Dshortcuts_dialog=false

The "Keyboard Shortcuts" menu item will be hidden from the UI when built without this feature.

Build and install

meson setup builddir --prefix=/usr
meson compile -C builddir
sudo meson install -C builddir

macOS

Meshy supports macOS 13+ with full native integration including CoreBluetooth (BLE), CoreLocation (GPS), USB serial, and camera support.

Option 1: Homebrew Cask (Recommended)

The easiest installation method for developers:

brew tap jreznik/meshy https://codeberg.org/jreznik/homebrew-meshy
brew install meshy

This installs a 15 MB bundle that uses GTK4 and libadwaita from Homebrew. All dependencies are installed automatically.

To update:

brew upgrade meshy

To completely uninstall (including app data):

brew uninstall --zap meshy

Option 2: Standalone DMG

For users who don't want to install Homebrew, a fully self-contained DMG is available:

Download: Meshy-Standalone-20260610.dmg (151 MB)

Installation:

1. Download the DMG
2. Open the DMG file
3. Drag Meshy.app to your Applications folder
4. Launch Meshy from Applications

The standalone bundle includes everything: Python 3.14, GTK4, libadwaita, and all dependencies. No additional software needs to be installed.

Building from Source on macOS

Prerequisites:

# Install Homebrew dependencies
brew install python@3.14 gtk4 libadwaita libshumate meson ninja
# Install Python packages (required for BLE, GPS, camera, notifications)
pip3.14 install pycryptodome pyserial segno pygobject \
 pyobjc-framework-Cocoa \
 pyobjc-framework-CoreBluetooth \
 pyobjc-framework-CoreLocation \
 pyobjc-framework-AVFoundation \
 pyobjc-framework-Vision \
 pyobjc-framework-UserNotifications \
 pyobjc-framework-libdispatch

Build and run:

meson setup builddir --prefix=/usr/local
meson compile -C builddir
PANGOCAIRO_BACKEND=fc ./builddir/src/meshy

Note: When using the Homebrew Cask or creating app bundles with the build scripts, all Python dependencies are bundled automatically.

Or create a Homebrew-style app bundle:

./build-aux/macos/build-homebrew-bundle.sh
open dist-homebrew/Meshy.app

Or create a fully self-contained bundle:

./build-aux/macos/create-standalone-bundle.sh
open dist/Meshy.app

See STANDALONE_BUNDLE_SUCCESS.md for technical details about the standalone bundle.

Development

Code Quality Tools

The project uses automated code quality checks via pre-commit hooks:

Setup (one time):

# Install pre-commit (Fedora)
sudo dnf install pre-commit ruff
# Or with pip
pip install --user pre-commit ruff
# Install git hooks
pre-commit install

What the hooks do:

• Ruff linter - Fast Python linter checking code style, imports, and common issues
• Ruff formatter - Automatic code formatting for consistent style
• i18n check - Validates that UI strings are marked translatable
• Standard checks - Trailing whitespace, EOF fixes, YAML validation, merge conflict detection

Usage:

Hooks run automatically on every commit:

git commit -m "Fix: something"
# Hooks run automatically and may modify files

Manual run on all files:

pre-commit run --all-files

Run just ruff:

ruff check src/
ruff format src/

See .pre-commit-hooks.md for detailed documentation.

Running Tests

Currently the project uses manual testing via the GUI. Automated unit tests for core modules (protocol, crypto, storage) are planned for future development.

Project Structure

• src/ - Python source code
  • views/ - UI view components (chat, channels, contacts, map, device, settings)
  • protocol.py - MeshCore protocol implementation
  • mesh_crypto.py - Cryptographic operations
  • storage.py - SQLite database management
  • models.py - Data models
• data/ - GTK resources, UI files, icons, schemas
• po/ - Translation files
• build-aux/ - Build scripts (AppImage)

Translations

Meshy uses Codeberg Translate (Weblate) for translations. If you'd like to help with translations, go check existing ones. If your language is in the list, you can start translating as a registered user. If it isn't among existing translations, file a ticket and request it.