MeshBay
MeshBay is a platform for private, encrypted, self-hosted groups with an application store. A group is a set of people, a set of directories on somebody's machine, and a set of applications over them — chat, files, video, music, photos. Files stay on the machine that shares them and travel encrypted, peer to peer; the hub only introduces machines to each other and never sees a file, a message or a key.
It is not a public file-sharing network. Public groups are an optional hub feature, and they are off on the reference deployment, meshbay.org.
your machine hub a member
──────────── ─── ────────
meshbay-node ◄─── signalling ────► accounts, ◄─── sign-in ───► browser
holds the files group list, or desktop
holds the group key introductions client
│ │
└──────────── encrypted, peer to peer, direct ───────────────────┘
Getting started
- Using MeshBay:
docs/QUICKSTART.mdturns one Linux machine into a node and invites a second person;docs/USERGUIDE.mdexplains every step. - Running your own hub:
docs/PACKAGING-GUIDE.md,docs/HTTPS.mdanddocs/MAIL-SERVER.md. - How it works:
docs/MESHBAY_DESIGN.mdis the architecture specification, anddocs/MESHBAY_NODE_PROTOCOL.mdthe wire format. - Programming against it:
docs/MESHBAY_HTTP_API.mdlists every route of the hub and of the node's control API, andexamples/has small Python programs that use them.
Repository layout
| Path | Contents |
|---|---|
packages/meshbay-common/ |
Shared cryptography and protocol types |
packages/meshbay-hub/ |
Hub server (FastAPI + PostgreSQL) and the web client it serves |
packages/meshbay-node/ |
Node daemon, its CLI and its local control UI |
packages/meshbay-cli/ |
Command-line client: a member's groups and files from a terminal |
packaging/ |
.deb, .rpm and Windows packaging, systemd units, Caddy and firewall configuration |
docs/ |
Design specification, protocol, HTTP API, user and operator guides |
examples/ |
Small Python programs using the hub, a node and its control API |
man/ |
Manual page for meshbay-node (meshbay-cli's is generated from its parser at build time) |
site/ |
Static website pages (not deployed) |
poc/ |
Early proof-of-concept scripts, kept for reference |
Development
Python 3.12 or later. All dependencies are declared in the packages'
pyproject.toml files:
python3 -m venv .venv
source .venv/bin/activate
pip install -e "packages/meshbay-common[dev]" -e "packages/meshbay-hub[dev]" \
-e "packages/meshbay-node[dev]" -e "packages/meshbay-cli[dev]"
.venv/bin/pytest
Licence
MeshBay is free software.
| Component | Licence |
|---|---|
packages/meshbay-common/ — the protocol and its cryptography, in Python |
LGPL-3.0-or-later (with the GPL-3.0 it builds on) |
The same layer in the clients: the files marked SPDX-License-Identifier: LGPL-3.0-or-later — in the interface, keyderive.js, crypto.js, playlist-crypto.js, transport.js and transport-*.js; on the desktop, keyring.js, transcripts.js and argon2-wasm.js; on Android, keys/Kdf.kt, keys/Keyring.kt and keys/Transcripts.kt; in the command-line client, client/keys.py |
LGPL-3.0-or-later |
| Everything else — hub, node, command-line client, the rest of the interface, the desktop and Android shells | AGPL-3.0-or-later |
The line is the protocol. Whatever a program needs to speak to a hub and a node —
key derivation, the identity bundle, sealing and opening, what is signed, the
wire codec and the transport — is under the Lesser GPL, in every language it
exists in, so a client may use it whatever its own licence; changes to those
files themselves stay under the LGPL. A file without an SPDX line has its
package's licence. Talking to a hub or a node over the network needs none of
this code and carries no condition at all. The rest is under the Affero GPL:
whoever runs a modified hub or node for other people must offer them its
source. The licence texts travel with the interface, in static/licenses/.
Group applications — the application store — may be under any licence, free
or not: the interface grants them that in an additional permission,
static/licenses/APPLICATION-EXCEPTION.txt,
as long as they use it only through the documented application interface
(docs/MESHBAY_DESIGN.md §9.2–9.4 and the modules the permission names). The
reference application, helloworld-app.js and its settings pane, is under 0BSD:
copy it to start one.
The Android application adds one permission to the AGPL, for the Google Play
services libraries the cast to a television goes through:
packages/meshbay-android/LICENSE-EXCEPTION.txt.
Third-party code keeps its own licence: the vendored browser libraries are
listed in static/vendor/PROVENANCE.md
with their texts in LICENSES.txt beside it, and every package build carries a
THIRD-PARTY-NOTICES.txt generated from what it actually ships
(packaging/third_party_notices.py).
Source
The repository is published read-only at https://git.meshbay.org/, and can be cloned with:
git clone https://git.meshbay.org/meshbay.git