LANMess
Install · Quick Start · Features · Threat Model · Security · Contributing
A serverless, end-to-end encrypted, terminal-based messenger for local networks and routed overlays.
LANMess discovers peers on the same broadcast domain over UDP, connects directly over TCP, and encrypts every message end-to-end with per-session X25519 ECDH and a symmetric hash ratchet. The local SQLite database is encrypted at rest under a random per-device master key, wrapped with your PIN via Argon2id.
No accounts. No phone numbers. No central server. No telemetry. No cloud.
Features
- End-to-end encryption. X25519 ECDH for session setup; AES-256-GCM for message payloads. Every control frame is signed with Ed25519.
- Forward secrecy. One-way HMAC-SHA256 ratchet per session. Old chain keys are erased after use.
- Encrypted local storage. The entire database is encrypted under a random per-device master key, recoverable only via Argon2id(PIN).
- Serverless discovery. UDP broadcast beacons with rotating TOTP-derived code tags. No registry, no directory.
- Add by code or by IP. Works on a LAN with broadcast discovery, or across routed overlays like Tailscale, WireGuard, and ZeroTier.
- Tamper-evident audit log. HMAC-chained security events inside the encrypted database.
- PIN lockout and panic password. Exponential lockout on failed attempts; a secondary password wipes the database on demand.
- Key rotation. Rotate Ed25519 and X25519 keys without re-adding contacts.
- Terminal UI. Contact list, chat log, unread badges, message history, slash commands, global search.
- Cross-platform notifications. Linux, macOS, Windows, and Termux.
Installation
LANMess requires Python 3.9 or later.
Install from PyPI:
pip install lanmess
Or from source:
git clone https://github.com/virensahti-nl/lanmess.git
cd lanmess
python -m pip install -e ".[test]"
Verify the install:
lanmess --version
Quick Start
Launch the app:
lanmess
On first launch you will be asked for:
- Display name. Shown to peers. 1 to 40 characters, no control characters.
- Group code. A shared secret of at least 12 characters. All peers that should discover and add each other must use the same group code. It is used once to derive shared keys and never stored in plaintext.
- PIN. A strong PIN of at least 12 characters, containing at least three of: lowercase, uppercase, digit, symbol. Used to unlock the local database.
The group code is only entered once. From then on, you unlock the app with your PIN.
Adding a contact
- On the peer's machine, press
Ctrl+Zto reveal the current 8-digit add code. - On your machine, enter that code in the "Add by 8-digit code" field.
- For routed networks, press
Iand enter the peer's IP, port, and code instead.
Starting a chat
- Select the contact in the left sidebar.
- Press
Sto send a chat request. The peer pressesYto accept. - Once a session is established, type messages in the input field and press Enter.
Press ? inside the app for the full list of shortcuts and slash commands.
Interface
Global keys
| Key | Action |
|---|---|
M |
Open the action menu |
? |
Show help |
Ctrl+Z |
Show your 8-digit add code |
Ctrl+F |
Search all messages |
Ctrl+L |
Lock the app |
Ctrl+Q |
Quit |
Chat shortcuts
| Key | Action |
|---|---|
A |
Focus the add-by-code input |
I |
Add by IP |
S |
Start or reconnect a chat |
Y / X |
Accept / reject a chat or add request |
C / D |
Clear history / delete contact |
T |
Stop the current chat session |
V |
Verify contact safety numbers |
Up / Down |
Navigate message history |
Slash commands
| Command | Action |
|---|---|
/help |
Show help |
/menu |
Open the action menu |
/addip |
Add by IP and port |
/address |
Show your IPs and port |
/code |
Show your add code |
/verify |
Show the safety number for the current contact |
/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 with the current contact |
/clearall |
Ask the peer to clear the history on both sides |
/stop |
Stop the chat session |
/del <id> |
Delete a specific message |
/del |
Delete the most recent message |
Security
The cryptographic primitives are Ed25519, X25519, AES-256-GCM, HKDF-SHA256, HMAC-SHA256, PBKDF2-HMAC-SHA256, and Argon2id. Message bodies are padded to 256-byte blocks to hide plaintext length. Database rows are bound to their context via AAD so ciphertexts cannot be swapped between rows.
LANMess defends against passive network observers, active network attackers without keys, replay, database theft, PIN brute-force, and offline brute-force of the panic password. It does not defend against a rooted device while unlocked, traffic analysis, a compromised peer, or a first-contact man-in-the-middle without out-of-band safety-number verification. It has not been independently audited.
The full threat model is in THREAT_MODEL.md. Reporting information and known limitations are in SECURITY.md.
Configuration and Storage
| Path | Purpose |
|---|---|
~/.lanmess/ |
Base directory, mode 0700 |
~/.lanmess/lanmess.db |
Encrypted SQLite database, mode 0600 |
~/.lanmess/lanmess.db-wal |
SQLite WAL file |
~/.lanmess/lanmess.db-shm |
SQLite shared memory file |
~/.lanmess/lanmess.db-journal |
SQLite rollback journal |
| Port | Protocol | Purpose |
|---|---|---|
50505/udp |
UDP broadcast | Discovery beacons |
50510-50600/tcp |
TCP | Peer-to-peer control and message frames |
The TCP port is chosen on first launch from the range and stored in the encrypted identity record. If the port is already in use on startup, a new one is selected automatically.
To back up LANMess, copy ~/.lanmess/lanmess.db (and the -wal and -shm files while the app is running) to a secure location. The backup is useless without the PIN.
Development
Clone the repository and install in editable mode:
git clone https://github.com/virensahti-nl/lanmess.git
cd lanmess
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
python -m pip install -e ".[test]"
Run the app locally:
python -m lanmess_files.main
Project layout
lanmess/
├── pyproject.toml
├── README.md
├── THREAT_MODEL.md
├── SECURITY.md
├── LICENSE
├── src/
│ └── lanmess_files/
│ ├── __init__.py
│ ├── config.py
│ ├── crypto.py
│ ├── database.py
│ ├── discovery.py
│ ├── network.py
│ ├── notifications.py
│ ├── tui.py
│ └── main.py
└── tests/
├── conftest.py
└── test_*.py
Testing
pytest
The suite covers the cryptographic primitives, KDFs, ratchets, padding, database migrations, audit log chaining, lockout and panic flows, discovery, network framing, protocol handlers, notifications, and outbox behavior.
Contributing
Issues and pull requests are welcome. Please:
- Open an issue before a large change so the design can be discussed.
- Include a test for any behavioral change.
- Run
pytestbefore opening a pull request. - For anything security-related, follow the note in
SECURITY.md.
License
MIT. See LICENSE.
LANMess is provided as-is, without warranty of any kind. Review the threat model before relying on it for sensitive communication.
Metadata
Release files for lanmess 1.1.12
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.12.tar.gz | 70.7 kB | With provenance | Details for lanmess-1.1.12.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lanmess-1.1.12-py3-none-any.whl | Python 3 | none | any | Details for lanmess-1.1.12-py3-none-any.whl |
Total release size: 127.7 kB
Release files / lanmess-1.1.12.tar.gz
| Download URL | lanmess-1.1.12.tar.gz |
|---|---|
| Size | 70.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
12015e8d4cf90896ba061a5fe4426832fb8f4cadf66610ebd9d50e250babbdac
|
|
BLAKE2b-256 checksum How to use checksums |
24a7d2da0afed9f279a8719b15c1d3d16c14b7f389bad8b6d1b47839a2f8cd37
|
| 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 15, 2026.
Transparency logRelease files / lanmess-1.1.12-py3-none-any.whl
| Download URL | lanmess-1.1.12-py3-none-any.whl |
|---|---|
| Size | 57.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
05a8b65cec6fde80065bcd4f700910592814bffaccbe7698613751061355597a
|
|
BLAKE2b-256 checksum How to use checksums |
3b702cf7960200bfb54269cb5d906ec0a8c7e50d259d87232ea903099d7c6a4b
|
| 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 15, 2026.
Transparency logSecurity for lanmess 1.1.12
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.12.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 15, 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.