Skip to main content

LANMess

Serverless, end-to-end encrypted, terminal-based messenger for your LAN and beyond.

PyPI Version License: MIT Python Versions


LANMess is a secure, serverless, peer-to-peer messenger that runs entirely in your terminal. It automatically discovers peers on your local network or connects directly via IP (perfect for Tailscale, WireGuard, or routed LANs). All messages are end-to-end encrypted, and your local database is protected by a PIN and Argon2id.

No servers. No cloud. No telemetry. Just pure, encrypted communication.

Features

  • Zero-Knowledge Architecture: Messages are encrypted with per-pair X25519 ECDH keys and AES-256-GCM. Ed25519 signatures prevent forgery.
  • Serverless Discovery: Automatically finds peers on the same broadcast domain using UDP multicast beacons.
  • Tailscale / VPN Ready: Add peers by IP and Port. Pinned addresses survive LAN changes and automatically route over your VPN.
  • Data at Rest: Your entire database (messages, contacts, identity) is encrypted using a random per-device master key, wrapped with your PIN via Argon2id.
  • Panic Password: Configure a secondary PIN that instantly wipes your local database and exits the app if you are ever forced to unlock your device.
  • Key Rotation: Compromised your keys? Rotate them seamlessly and notify your contacts via signed control frames.
  • Auto-Reconnect & Outbox: If a peer goes offline, your messages queue up. When they return, the session re-negotiates automatically and the outbox flushes.
  • Live Presence & Typing: See who is online (●) and when they are typing.
  • Global Search UI: Press Ctrl+F to search across all your messages and contacts.
  • Cross-Platform Notifications: Natively supports Linux, macOS, Windows, and Termux.
  • Rich TUI: A beautiful terminal interface with unread badges, replies, reactions, and command history.

Installation

Requires Python 3.9 or higher.

pip install lanmess

Quick Start

Start the application:

lanmess

First Launch

  1. Display Name: Choose a name (e.g., alice).
  2. Group Code: A shared secret (min 12 chars). All peers must use the same group code to discover each other.
  3. PIN: A strong PIN to unlock your local database.

Note: You only type the group code once. From then on, you unlock the app with your PIN.

Adding Contacts

  • By Code (A): Best for local LANs. Automatically finds the peer via broadcast discovery using their temporary 8-digit Add Code (Ctrl+Z).
  • By IP (I): Best for Tailscale or routed networks. Enter the peer's IP, Port, and Add Code manually.

Add-by-IP addresses are pinned. They will not be overwritten if the peer's local LAN IP changes.

Interface & Shortcuts

Global Keys

Key Action
M Open the main action menu
? Show help
Ctrl+Z Show your 8-digit Add Code
Ctrl+F Search all messages
Ctrl+L Lock the app (requires PIN to unlock)
Ctrl+Q Quit

Chat Shortcuts

Key Action
A Focus the "Add by Code" input
S Start or Reconnect a chat
Y / X Accept / Reject chat requests
C / D Clear history / Delete contact
T Stop the current chat session
V Verify contact safety numbers
Up / Down Navigate your message history

Slash Commands

Command Action
/help Show help
/find <text> Search messages with the current contact
/reply <id> <text> Reply to a specific message
/react <id> <emoji> React to a specific message
/clear Clear local history
/clearall Ask the peer to clear the history on both sides
/stop Stop the chat session
/del <id> Delete a specific message

Security Model

LANMess is designed to be secure against passive network observers and casual device access.

  • Signatures: Every control frame (Add, Chat, Clear, Presence, Typing, Rotate) is signed with Ed25519.
  • Forward Secrecy: Session chains use a symmetric hash ratchet. Old chain keys are deleted from memory after use.
  • Padding: Messages are padded to 256-byte blocks to prevent length inference.
  • Safety Numbers: TOFU (Trust On First Use) is mitigated by displaying a 60-digit safety number. Press V to verify your peers out-of-band.
  • Audit Log: All security-relevant events (failed PINs, key rotations, signature failures) are stored in an HMAC-chained audit log inside your encrypted database.

For a full breakdown of what is and isn't defended (including traffic analysis and compromised peers), please read THREAT_MODEL.md.

Development

To develop locally, clone the repo and install in editable mode with test dependencies:

git clone https://github.com/yourname/lanmess.git
cd lanmess
pip install -e ".[test]"

Run the test suite (251 tests):

pytest

License

This project is licensed under the MIT License. See the LICENSE file for details.

Metadata

Release files for lanmess 1.1.11

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lanmess 1.1.11
File Size Uploaded Provenance Actions
lanmess-1.1.11.tar.gz 59.0 kB With provenance Details for lanmess-1.1.11.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lanmess 1.1.11
File Interpreter ABI Platform Actions
lanmess-1.1.11-py3-none-any.whl Python 3 none any Details for lanmess-1.1.11-py3-none-any.whl

Total release size: 103.4 kB

Release files / lanmess-1.1.11.tar.gz

Download URL lanmess-1.1.11.tar.gz
Size 59.0 kB
Tags Source
SHA-256 checksum
How to use checksums
c3ee5b03140ba94a758280710ac1eb76297a33a5828e2c773292cd80aa55f34c
BLAKE2b-256 checksum
How to use checksums
647c601c81eb33e439faf4a8c052e18fd2ab7f418a25681f07d86564d1079915
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / lanmess-1.1.11-py3-none-any.whl

Download URL lanmess-1.1.11-py3-none-any.whl
Size 44.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a9ee79211605df5e0d09e0c7ed716e5bc028c5ec2eb7229aace284ed4487fdc8
BLAKE2b-256 checksum
How to use checksums
7eff9f7febb672e5107b2518d05e9878962daf81697a040f5e93b5886081d4da
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for lanmess 1.1.11

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for lanmess-1.1.11.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page