Chapter 1 — Introduction¶

What is Stolo?¶

Stolo is an infrastructure-free, end-to-end encrypted communications platform. It lets teams exchange messages, files, voice notes, and live positions without cell towers, internet, or any central server — and seamlessly uses those networks when they are available.

Stolo is built for teams that operate where connectivity is unreliable or absent: field operations, emergency response, remote industrial sites, maritime and expedition work, and privacy-conscious organizations.

Every Stolo device is a node in a self-forming mesh network. Devices find each other automatically over WiFi, long-range LoRa radio, and the internet, and messages automatically take whatever path is available — if one path drops, traffic reroutes over another without any user action.

Key capabilities¶

Capability	Description
1:1 secure messaging	End-to-end encrypted direct messages with plain-language delivery tracking (Sent → Relayed → Delivered).
Group messaging	Owner-managed groups with per-member delivery visibility.
Attachments	Photos (automatically compressed to suit the link), files, and push-to-talk voice notes.
Delivery modes	Standard, Priority (held on a relay if the recipient is offline), and Critical (retried until delivered or cancelled).
Live map	Team positions on a geographic map plus a mesh-topology view showing exactly how each teammate is reached.
Multi-transport networking	Local WiFi auto-discovery, LoRa radio (RNode hardware over USB or Bluetooth), and internet gateway links — all active simultaneously.
Trust & quarantine	Messages from unknown senders are held in quarantine until an operator explicitly trusts the sender, their organization, or accepts a single message.
Blocking	Time-boxed or permanent blocks enforced at the network layer.
Organizations	Publisher identities that let fleets of devices be trusted as a unit.
Vendor verification	Cryptographic "genuine Stolo" device certificates, shown as a badge on peers.
Relay nodes	Any device — typically a Raspberry Pi — can be deployed as an always-on relay/transport node to extend coverage.

Architecture¶

A Stolo installation has two halves:

┌─────────────────────┐      WebSocket       ┌──────────────────────┐
│                     │  (JSON on 127.0.0.1) │                      │
│   Stolo App (UI)    │◄────────────────────►│   Stolo Engine       │
│                     │                      │   (Reticulum + LXMF) │
│  • Conversations    │                      │                      │
│  • Map / Mesh view  │                      │  • Identity & keys   │
│  • Connections      │                      │  • Peer discovery    │
│  • Team roster      │                      │  • Message routing   │
│  • Settings         │                      │  • Encryption        │
└─────────────────────┘                      │  • Radio / network   │
                                             │    interfaces        │
                                             │  • Local storage     │
                                             └──────────┬───────────┘
                                                        │
                                                        ▼
                                     ┌──────────────────────────────────┐
                                     │        The Stolo Mesh            │
                                     │                                  │
                                     │  • Local WiFi (auto-discovery)   │
                                     │  • LoRa Radio (RNode, USB/BLE)   │
                                     │  • Internet (Stolo Gateway /     │
                                     │    custom Reticulum nodes)       │
                                     └──────────────────────────────────┘

The app is the user interface, available on iOS, Android, macOS, Windows, and Linux. On mobile the engine runs embedded inside the app; on desktop it runs as a companion process.
The engine owns all networking and cryptography. It is built on Reticulum, a proven cryptography-first networking stack, and LXMF, its store-and-forward message format. The engine keeps working across any mix of transports and stores conversations locally on the device — there is no Stolo cloud that sees your messages.
The app and engine communicate only over a local, token-authenticated WebSocket on the device itself (127.0.0.1:4848). Nothing on the network can drive the engine.

Core concepts¶

Understanding these six concepts will make everything else in this guide straightforward.

Connections (interfaces)¶

A connection is a path your messages can travel. Stolo runs every enabled connection at the same time and reroutes automatically when one drops. There are three families:

Local WiFi — automatic discovery of teammates on the same network. No configuration, no router dependency; devices find each other directly.
LoRa Radio — an RNode LoRa radio attached over USB or Bluetooth gives kilometers of range with no infrastructure at all. Low bandwidth, very long reach.
Internet — a link to a Reticulum node over the internet (by default, the Stolo Gateway at gw.stolo.io) connects distant teams whenever any internet path (WiFi, LTE) exists.

See Chapter 5 — Connections & Networking.

Reach¶

Every person in Stolo wears a reach indicator answering "can I reach them right now?" in plain language:

Direct — connected directly, strong link.
Via relay — reachable through one or more intermediate nodes; expect a short delay.
Finding… — no route currently known; Stolo is searching. Messages you send are held safely and delivered the moment a path returns.

Delivery modes¶

Each conversation can send with one of three modes:

Standard — delivers as soon as there's a path.
Priority — additionally queued and retried automatically (up to 10 retries) if the recipient is offline.
Critical — retried indefinitely until delivered or you cancel it.

Identity¶

Each device generates its own cryptographic identity on first launch — a keypair that is the device's address on the mesh. There is no account, no phone number, and no sign-up. Identities never leave the device.

Trust and quarantine¶

Stolo is default-deny for unknown senders. A message from a sender you haven't trusted is held in Quarantine — never silently delivered — until an operator reviews it and decides: trust the sender, trust their whole organization, accept just this one message, or deny (optionally blocking the sender). See Chapter 7 — Team, Trust & Blocking.

Organizations¶

An organization is a publisher identity that can vouch for member devices. Trusting an organization means messages from any device verified as belonging to it are delivered without individual approval — the right model for fleets. See Chapter 8 — Organizations & Vendor Verification.

About this guide¶

This guide is written for the people who deploy and administer Stolo: IT staff, comms leads, and power users. It covers every screen and function of the app, the underlying engine behavior an administrator should understand, deployment of relay nodes, the security model, and troubleshooting.

Chapter	Contents
2 — Getting Started	Platforms, installation, licensing and activation, first launch.
3 — Conversations & Messaging	Messages, delivery tracking, attachments, voice, reactions.
4 — Groups	Creating and managing groups, per-member delivery.
5 — Connections & Networking	WiFi, LoRa/RNode radios, internet nodes, radio regions.
6 — Map & GPS	Geographic map, mesh view, position sharing, background mesh.
7 — Team, Trust & Blocking	Roster, trust lifecycle, quarantine, blocking.
8 — Organizations & Vendor Verification	Org identities, trusted fleets, vendor certificates.
9 — Licensing	Seats, activation codes, App Store subscriptions, expiry.
10 — Security Reference	Encryption, key storage, threat model, hardening.
11 — Deployment	Relay nodes on Raspberry Pi, gateways, fleet practices.
12 — Settings Reference	Every setting in the app, with defaults.
13 — WebSocket API Reference	The local automation/integration API.
14 — Maintenance & Troubleshooting	Data locations, resets, timeouts, common issues.

A note on names. Stolo's engine and data directories use the platform codename GridX (for example the ~/.gridx data directory and the gridx service on relay nodes). Where a file path or service name says gridx, it is part of Stolo.