Mesh-Talk

A serverless, end-to-end-encrypted messenger for your local network. Mesh-Talk peers find each other on the LAN and talk directly — no account, no cloud, no server in the middle. Your messages and files never leave the network, and they stay encrypted the whole way.

Documentation · Architecture · Report Bug · Request Feature

---

Overview

Mesh-Talk is a desktop chat app (Tauri v2 + React) for macOS, Windows, and Linux, built on a UI-free Rust protocol core (mesh-talk-core) that also runs headless as the mesh-talk-node CLI. Peers discover one another over signed UDP multicast, connect over a Noise-encrypted TCP channel, and converge by replicating a per-conversation append-only event log. Every message is end-to-end encrypted with forward secrecy; an optional store-and-forward relay (the "post office") delivers messages to peers that are temporarily offline.

Features

Messaging

• One-to-one DMs and group channels, addressed by identity (and fanned out across a user's linked devices)
• Reactions, @mentions, replies/threads, and full-text search over local history
• Large-file transfer (up to ~4 GiB) — chunked, encrypted per chunk, with progress and resume
• Persistent, offline-capable history; a "post office" relay delivers to peers that are away

Security & privacy

• End-to-end encryption with forward secrecy — Double Ratchet for DMs, a sender-key ratchet for channels
• Ed25519 device identities (your ID is your key fingerprint), X25519 key agreement, Noise-encrypted transport
• Safety-number contact verification with trust-on-first-use and key-change warnings
• Encrypted-at-rest keystores and message logs; no servers, no telemetry, no central account

Network

• Zero-config LAN discovery: signed UDP multicast announces + announce/response + a unicast subnet-scan fallback
• Dual-stack IPv4/IPv6 direct TCP; self-healing discovery that re-announces and re-joins on network changes

Desktop experience

• Multi-device accounts with QR/code device linking
• Live presence (online / last-seen), pinned contacts, and an in-app diagnostics panel
• Tray icon, launch-at-login, native notifications, light / dark / OLED themes, and English / 中文

Screenshots

Built-in animated stickers	Selectable themes
End-to-end verification (safety number)	Background & privacy settings
Pick an avatar	Group avatars

How it works

1. Discover — each peer broadcasts a signed announce over UDP multicast (224.0.0.167:47474) on every interface; peers verify the signature and record one another. A unicast subnet scan and announce/response replies cover networks where multicast is flaky.
2. Connect — peers dial each other over TCP and run a Noise handshake for an authenticated, encrypted channel.
3. Sync — conversations are append-only event logs; peers exchange only the events the other is missing (bounded rounds), so history converges and survives restarts.
4. Encrypt — message payloads are sealed with per-conversation ratchets (Double Ratchet / sender key), so a compromised key can't decrypt past traffic.
5. Relay when offline — if a recipient is away, an elected post-office node holds the encrypted events and forwards them on reconnect. It never sees plaintext.

See docs/ARCHITECTURE.md for the full design.

Download & first run

Grab the .zip for your OS/arch from the Releases page (e.g. mesh-talk_vX.Y.Z_macos_arm64.zip) and unzip it — inside are the installer(s) for your platform plus a SHA256SUMS file. The builds are free and unsigned (no paid Apple/Windows code-signing certificate), so macOS and Windows show a one-time "unidentified developer" / SmartScreen prompt the first time — this is expected for unsigned open-source software and does not mean the app is unsafe. Every release also ships a SHA256SUMS list, a Sigstore cosign signature, and a SLSA build-provenance attestation; the release page documents the exact verify commands (shasum -c, cosign verify-blob, gh attestation verify). How to open, per platform:

• Linux — no prompt at all.
  • AppImage (portable, no install): chmod +x Mesh-Talk_*.AppImage && ./Mesh-Talk_*.AppImage
  • or install the .deb / .rpm (adds an app-menu entry): sudo dpkg -i mesh-talk_*.deb
• macOS — open the .dmg, drag mesh-talk to Applications. On first launch macOS blocks an unsigned app, so right-click the app → Open → Open (only needed once). If it says "damaged", clear the quarantine flag with the full path (a Homebrew/Conda xattr in PATH may shadow the system one and lack -r): /usr/bin/xattr -dr com.apple.quarantine /Applications/mesh-talk.app.
• Windows — run the .exe (or .msi) installer. SmartScreen shows "Windows protected your PC" → click More info → Run anyway (only the first time). WebView2 is fetched automatically if missing.

After the one-time approval it behaves like any installed app. To remove the prompt entirely you'd need paid signing (Apple Developer ID for macOS, a code-signing cert or the Microsoft Store for Windows); Linux is always prompt-free.

Two peers must be on the same LAN with the firewall allowing UDP 47474 (multicast 224.0.0.167) and the app's TCP port. If they can't see each other, the in-app Diagnostics panel and the troubleshooting guide walk through it.

Build from source

Prerequisites

• Rust (stable, edition 2021) + Cargo
• Node.js 20+ (frontend toolchain)
• Tauri CLI — cargo install tauri-cli
• Linux only — the GTK/WebKit stack: sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev patchelf

Desktop app

git clone https://github.com/OctopusGarage/mesh-talk.git
cd mesh-talk
make dev          # install Rust + Node deps + git hooks (first run is slow)
make tauri-dev    # run the app in dev mode (hot-reload frontend)
make tauri-build  # or: produce a release bundle (.app / .dmg / .exe / .deb / ...)

Headless node (CLI / post-office relay)

The same core runs without a UI as mesh-talk-node — also the offline-delivery relay:

cargo run --bin mesh-talk-node -- --keystore alice.ks --password <pw> --name alice

Flag	Meaning
--keystore <path>	encrypted identity keystore, created if absent (required)
--password <pw>	password that encrypts the keystore (required)
--name <name>	display name advertised to peers (required)
--port <n>	TCP port to listen on (0 = OS-assigned)
--discovery-port <n>	UDP discovery port, default 47474 (must match across peers)
--post-office	run as a store-and-forward relay for offline delivery (no chat REPL)

Each instance needs its own keystore path — two nodes sharing one clobber each other's data. In the chat REPL: /msg <peer-id-prefix> <text> to DM, /history <peer-id-prefix> to view a thread.

Architecture

Two Rust crates plus a React frontend, layered so the protocol is independent of the UI:

mesh-talk/
├── crates/mesh-talk-core/   # UI-free protocol SDK (no Tauri dep)
│   ├── src/
│   │   ├── node/            # the serverless node: orchestration
│   │   ├── identity/  transport/  discovery/  eventlog/
│   │   ├── ratchet/  channel/  dm.rs  file/  postoffice/
│   │   ├── storage/         # encrypted append-only logs + at-rest crypto
│   │   ├── util/            # shared helpers (net, safety-number, …)
│   │   └── bin/mesh-talk-node.rs   # headless node CLI (--post-office relay mode)
│   └── tests/               # multi-process integration tests (real nodes over UDP/TCP)
├── src-tauri/               # Tauri desktop shell — a thin bridge over mesh-talk-core
├── frontend/                # React + TS + Tailwind + shadcn ("Ink & Signal" design)
├── docs/                    # architecture + documentation map
├── specifications/          # process, deployment, and convention docs
└── Makefile                 # dev/build/test/e2e/lint shortcuts

The frontend talks to the backend only through Tauri commands; the desktop crate holds no protocol or crypto logic. Wire formats are versioned bincode framed with a magic + version byte. Full reference: docs/ARCHITECTURE.md.

Documentation

Everything is indexed in the documentation map — start there. Highlights:

• Architecture — components, data flow, and crypto
• Contributing — dev setup, commands, and conventions
• Domain model and repo conventions
• Deployment · Troubleshooting · Security

Development

make tauri-dev    # run the desktop app (hot reload)
make test         # Rust workspace unit tests
make e2e          # multi-process backend E2E (real nodes)
make lint fix     # clippy -D warnings · auto-fix + format
make check        # the full local health gate

The UI flow is covered by a Playwright suite (cd frontend && npm run e2e). Quality is enforced in CI across macOS/Windows/Linux — formatting, Clippy (-D warnings), tests + coverage, the frontend build + ESLint, supply-chain policy (cargo deny), unused-dep and spelling checks — plus fuzzing, mutation testing, secret scanning, and OpenSSF Scorecard. Commits are GPG-signed (the hooks set up by make dev enforce it). See CONTRIBUTING.md for the full workflow.

Contributing

Contributions are welcome — see CONTRIBUTING.md for the dev setup, build/test/lint commands, and conventions, and CODE_OF_CONDUCT.md for the community guidelines.

Security

Mesh-Talk is end-to-end encrypted with forward secrecy and has no servers or telemetry. Please report vulnerabilities privately — see SECURITY.md. Do not open a public issue for security reports.

License

Open source under the MIT License.

(back to top)