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+Fto 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
- Display Name: Choose a name (e.g.,
alice). - Group Code: A shared secret (min 12 chars). All peers must use the same group code to discover each other.
- 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
Vto 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.