# 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](https://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.md`](docs/QUICKSTART.md) turns one Linux
  machine into a node and invites a second person;
  [`docs/USERGUIDE.md`](docs/USERGUIDE.md) explains every step.
- **Running your own hub:** [`docs/PACKAGING-GUIDE.md`](docs/PACKAGING-GUIDE.md),
  [`docs/HTTPS.md`](docs/HTTPS.md) and [`docs/MAIL-SERVER.md`](docs/MAIL-SERVER.md).
- **How it works:** [`docs/MESHBAY_DESIGN.md`](docs/MESHBAY_DESIGN.md) is the
  architecture specification, and
  [`docs/MESHBAY_NODE_PROTOCOL.md`](docs/MESHBAY_NODE_PROTOCOL.md) the wire format.

## 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 |
| `packaging/` | `.deb`, `.rpm` and Windows packaging, systemd units, Caddy and firewall configuration |
| `docs/` | Design specification, protocol, user and operator guides |
| `man/` | Manual page for `meshbay-node` |
| `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:

```bash
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]"
.venv/bin/pytest
```

## Source

A read-only public mirror is browsable at <https://git.meshbay.org/> and can be
cloned with:

```bash
git clone https://git.meshbay.org/meshbay.git
```