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.

Scope. Linux only: Ubuntu/Debian and Fedora. Windows is covered by PACKAGING-GUIDE.md and is not repeated here. This guide uses meshbay.org as the hub; running your own is PACKAGING-GUIDE.md plus HTTPS.md and 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:

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:

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.

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:

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:

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

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:

meshbay-node status

You want to see daemon running. If not:

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:

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:

meshbay-node group add "Family Photos" --dir ~/Pictures/shared
meshbay-node reload
meshbay-node gek init --group "Family Photos"

What those three did:

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?

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:

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.

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

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

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?

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:

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