# MeshBay — Quickstart This guide takes one Linux machine, turns it into a MeshBay node, creates a group over a directory on it, and invites a second person. It assumes you can use a terminal. It assumes nothing else. For what each step *means* — and for everything this guide leaves out — read [`USERGUIDE.md`](USERGUIDE.md). > **Scope.** Linux only: Ubuntu/Debian and Fedora. Windows is covered by > [`PACKAGING-GUIDE.md`](PACKAGING-GUIDE.md) and is not repeated here. This > guide uses **meshbay.org** as the hub; running your own is > [`PACKAGING-GUIDE.md`](PACKAGING-GUIDE.md) plus [`HTTPS.md`](HTTPS.md) and > [`MAIL-SERVER.md`](MAIL-SERVER.md). --- ## What you are building ``` your machine meshbay.org your friend ──────────── ─────────── ─────────── meshbay-node ◄─── signalling ────► hub ◄─── sign-in ───► browser holds the files accounts, or desktop holds the group key group list, client decides who is served introductions │ │ └──────────── encrypted, peer to peer, direct ──────────────────┘ (your files never touch the hub) ``` Three things, and it is worth knowing which is which before you start: | | What it is | |---|---| | **The hub** | An address book and a switchboard. It holds your account and your group's name, and introduces two machines to each other. It never sees a file, a message or a key. | | **The node** | A daemon on *your* machine. It holds the directories you share and the key that encrypts them. It decides who gets served. This is the part you install. | | **The client** | The web app the hub serves, or the desktop application. This is what you and your members look at. | --- ## Before you start - [ ] **A Linux machine that stays on.** Your files are served from it, so a laptop that sleeps is a group that is offline half the time. A spare mini-PC, a home server or an always-on desktop is the right shape. - [ ] **A directory to share**, with something in it. - [ ] **An email address** you can read — account sign-up sends a code to it. - [ ] **About half an hour**, plus however long a first index takes — which depends on how much you are sharing, and does not need watching. - [ ] **Terminal access** to that machine. Everything below works over SSH; no graphical session is needed on the node. You do **not** need a static IP, a domain name, port forwarding, or a router you control. Two residential ISPs have been measured working without any of it. --- ## Step 1 — Download the packages From **https://meshbay.org/downloads**, take the ones for your distribution: | | Ubuntu / Debian | Fedora | |---|---|---| | **`meshbay-common`** — required, install it first | `.deb` | `.rpm` | | **`meshbay-node`** — the daemon that hosts your files | `.deb` | `.rpm` | | `meshbay-client` — the desktop application, optional | `.deb` | `.rpm` | You need the first two. The desktop application is worth having if this machine has a screen, but nothing in this guide requires it: a terminal and a browser are enough. Put them in one directory — the next step installs them together. --- ## Step 2 — Install Install **with your package manager, not with `dpkg -i` / `rpm -ivh`**. Both of those ignore weak dependencies, and the video drivers that let this machine re-encode a film without melting are weak dependencies. ```bash cd ~/Downloads # wherever you put them # Ubuntu / Debian sudo apt install ./meshbay-common_*.deb ./meshbay-node_*.deb # Fedora sudo dnf install ./meshbay-common-*.rpm ./meshbay-node-*.rpm ``` Add `./meshbay-client_*` to that line to install the desktop application too. `meshbay-common` carries everything the others need, so there is nothing else to install and no Python environment to set up. **ffmpeg**, required for video streaming, comes in as a recommended dependency of the command above; without it the node refuses to start and says so. Check it landed: ```bash meshbay-node status ``` It will report that there is no keystore. That is the next step. --- ## Step 3 — Create your account Open **https://meshbay.org** in a browser and register. Three things on that page are worth slowing down for: 1. **Your passphrase is not a password.** It never reaches the hub. It encrypts the copy of your identity keys that lives on every node you join, and nobody — not the hub, not an operator, not us — can reset it. The floor is 12 characters; **four unrelated words** is the shape that actually works. 2. **Your recovery key is shown exactly once.** It is a 32-byte secret that can restore your access to your groups if you forget the passphrase. Put it in a password manager before clicking past it. Lose both it and the passphrase and your files are still there — but every group has to be rejoined by hand, with a new identity. 3. **Verify your email.** A code arrives; the account is inactive until you enter it. --- ## Step 4 — Set up the node Back on the node machine: ```bash meshbay-node init ``` It asks for the hub URL (press Enter for `https://meshbay.org`) and your hub username. Then it writes `~/.config/meshbay/node.toml`, creates the keystore, and prints something like: ``` Node key: 7mK2p...base64...= ``` **Copy that key.** In your browser, on meshbay.org: **Settings → Link Node**, paste it, submit. This is what lets the hub introduce your members to this machine. It is a public key; it identifies the node and unlocks nothing. --- ## Step 5 — Start the node ```bash systemctl --user enable --now meshbay-node loginctl enable-linger $USER # keep serving when you are not logged in ``` `enable-linger` is not optional on a machine you reach over SSH. Without it, systemd stops your user services when your session ends — the group goes dark the moment you disconnect. Check: ```bash meshbay-node status ``` You want to see `daemon running`. If not: ```bash journalctl --user -u meshbay-node -f ``` ### If your files live outside your home directory The node unit is hardened: it can only write inside `~/.config/meshbay` and `~/.local/share/meshbay`. An external drive or a second partition needs a drop-in, and it needs **both** lines: ```bash mkdir -p ~/.config/systemd/user/meshbay-node.service.d cat > ~/.config/systemd/user/meshbay-node.service.d/paths.conf <<'EOF' [Service] ReadWritePaths=/mnt/library RequiresMountsFor=/mnt/library EOF systemctl --user daemon-reload systemctl --user restart meshbay-node ``` `RequiresMountsFor` matters as much as `ReadWritePaths`. The service runs in its own mount namespace, so a volume mounted *after* it started is invisible to it — and the symptom is a directory that reads as empty while everything else looks correct. --- ## Step 6 — Create the group In the browser, on meshbay.org: **Create group** in the sidebar. - **Name** — anything. It is shown to members as `name@yourusername`. - **Join policy** — leave it on **Invite only**. The alternative, *Open*, lists the group publicly and lets anyone in, including the hub. There are groups that want that; a first one is not it. - **Description** — optional, shown to members on their home page. The group now exists on the hub and has no files, no key and no host. The next step is all three. --- ## Step 7 — Hand the group to your node Back on the node machine. Use the same name you just typed: ```bash meshbay-node group add "Family Photos" --dir ~/Pictures/shared meshbay-node reload meshbay-node gek init --group "Family Photos" ``` What those three did: | | | |---|---| | `group add` | told the node to host that group, and made the directory its first shared folder. It is **read-write** by default, so members can upload into it. Add `--no-writable` if you want a published, read-only library. | | `reload` | made the running daemon re-read its config without dropping anyone. | | `gek init` | generated the group's encryption key. **Nothing works before this** — the key never leaves your node, and every member receives it wrapped for their own key, on every connection. | The node starts indexing immediately. A large library takes a while; you can watch it with `meshbay-node status` or in the group page, which shows the progress. Want more than one directory in the group? ```bash meshbay-node root add /mnt/library/films --name Films meshbay-node root add /mnt/usb/archive --removable # external drive meshbay-node root list ``` Roots added later are **read-only by default** — the opposite of the first one, deliberately. Pass `--writable` if members should be able to upload there. --- ## Step 8 — Pair your browser Your node does not take orders from the hub. Before your browser can invite anyone or delete a file, the node has to recognise it: ```bash meshbay-node operator pair ``` It prints a code like `R3H8-TB6V`, valid 24 hours. In the browser, open your group → **Members** tab → enter the code. The code never passes through the hub. That is the whole point of it: a hub that could name your operator key could make itself your node's administrator. --- ## Step 9 — Let people reach you WebRTC picks a fresh UDP port per connection, so there is no single port to forward. What the node needs is to **accept unsolicited inbound UDP on your LAN** — browsers announce themselves with an address the node cannot resolve, so the browser must be able to call the node, not the reverse. ```bash # Ubuntu — your LAN, never "anywhere" sudo ufw allow from 192.168.0.0/16 app "MeshBay Node" # Fedora — apply to the zone holding your LAN interface sudo firewall-cmd --permanent --zone=FedoraWorkstation --add-service=meshbay-node sudo firewall-cmd --reload ``` **Scope it to the LAN.** This profile opens UDP 1024-65535; it does not belong in an internet-facing zone. Members outside your network are reached by hole punching, which needs no open port at all. The node's own admin surface is not affected: it listens on loopback only, behind a token, and is never network-exposed. --- ## Step 10 — Invite someone Your friend needs a meshbay.org account first — send them to Step 3. Then, with their username: ```bash meshbay-node member invite alice_dupont ``` You get: ``` INVITATION CODE K7P2-9WQX valid until 2026-09-25T17:40:00Z ``` Send that code however you normally talk to them — message, mail, out loud. It works once, for that account only, for that group only, and the hub never sees it. You do not need to be online when they use it. You can do the same thing from the **Members** tab of the group, from the browser you paired in Step 8. --- ## Step 11 — What your friend does 1. Signs in at **https://meshbay.org**. 2. The group is already in their sidebar — creating the invitation registered their membership. 3. They open it and are asked: *"This node needs to recognise you."* They paste the code. 4. That is it. Your node pins their key, wraps the group key for it, and their files appear. They will not be asked again on that browser. A *different* browser on the same node recovers the same identity with their passphrase alone. A different *node* — someone else's group — asks for a code again, as first contact always does. --- ## Did it work? ```bash meshbay-node status ``` A healthy node reads roughly like this: ``` hub https://meshbay.org (user yourname) node key 7mK2p...= daemon running — ok node_id 82.65.x.x:0 groups 1 files 4213 peers 1 config /home/you/.config/meshbay/node.toml group Family Photos [private] 8f3c... shared → /home/you/Pictures/shared (rw) operator yourname key AAAC3NzaC1lZDI1… paired 2026-09-18T14:02:11Z ``` If a line is missing, `status` names the command that fixes it. The four that catch most people: | Symptom | Cause | |---|---| | `daemon not running` | Step 5, or a startup error in `journalctl --user -u meshbay-node` | | `operator NONE PAIRED` | Step 8 — invites and file deletion are refused until this is done | | an `action needed:` block naming a group key | Step 7's `gek init` was skipped — `meshbay-node group list` shows it as `NO KEY` | | Group shows files to you, nothing to a member | The member never redeemed a code, or the firewall in Step 9 | --- ## Where to go next - **Point Videos, Music and Photos at their folders.** Group → Settings — as many folders as each library needs. Until you do, those tabs stay empty and say so. - **Turn off the applications you do not want.** Group → Members → Applications. Files and Settings always stay. - **Add your other devices.** Your phone's browser, the desktop application: each one asks to be recognised, and you approve it from a device already linked. Nobody else is involved. - **Read [`USERGUIDE.md`](USERGUIDE.md)** — what each application does, how members are managed, what happens when someone leaves, what is private and what is not, and what to do when something breaks.