path: root/docs/QUICKSTART.md

# 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: **Profile → Link Node**,
paste it, submit. It is on the Profile page, not Settings — next to your
passphrase and recovery phrase, which is where everything tied to your identity
rather than to this browser lives.

This is what lets the hub introduce your members to this machine. It is a
public key; it identifies the node and unlocks nothing.

If you lose it, `meshbay-node status` prints it again at any time. Those are the
two places it can be read — that command, and **Node → Overview** in the desktop
client. A browser cannot reach the node's own control API, so it cannot show you
the key; pasting it here once is what a browser-only operator does instead.

---

## 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.

Someone with no account yet gets a link instead, bound to their e-mail address:
`meshbay-node member invite alice@example.org --link`. They open it, register
with that address, and land in the group without typing a code
([`USERGUIDE.md` §7](USERGUIDE.md#7-managing-people)).

You can do the same thing from the **Members** tab of the group, from the
browser you paired in Step 8. There, **Send the invitation by e-mail** is ticked
by default and has the hub mail the code for you — which means the hub reads it.
Untick it and share the code yourself when that matters; the box remembers.

---

## 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.