MeshBay — Installation Guide

Four packages, all installed under /opt/:

Pick what you need: a desktop user installs common + node + client. A server running the hub installs common + hub.

Ubuntu / Debian

Install

sudo dpkg -i meshbay-common_0.9.0_amd64.deb
sudo dpkg -i meshbay-node_0.9.0_amd64.deb      # desktop machine
sudo dpkg -i meshbay-hub_0.9.0_amd64.deb        # server only
sudo dpkg -i meshbay-client_0.9.0_amd64.deb     # desktop machine

If dpkg complains about missing dependencies:

sudo apt-get install -f

Uninstall

sudo dpkg --remove meshbay-client meshbay-hub meshbay-node meshbay-common
sudo rm -rf /opt/meshbay-*

Fedora / RHEL

Install

sudo rpm -ivh meshbay-common-0.9.0-1.fc44.x86_64.rpm
sudo rpm -ivh meshbay-node-0.9.0-1.fc44.noarch.rpm      # desktop machine
sudo rpm -ivh meshbay-hub-0.9.0-1.fc44.noarch.rpm        # server only
sudo rpm -ivh meshbay-client-0.9.0-1.fc44.x86_64.rpm     # desktop machine

Uninstall

sudo rpm -e meshbay-client meshbay-hub meshbay-node meshbay-common

Windows

One installer, MeshBay-Setup-<version>.exe, carries the client and the node (with meshbay-common inside it). There is no Windows hub.

Install

Run the installer. It is per-user and lands in %LOCALAPPDATA%\Programs\MeshBay\ without needing admin rights. The node daemon ships beside the app at resources\node-runtime\meshbay-node.exe; the client finds it automatically.

It asks two things, both skippable:

• "Run MeshBay Node as a background service?" — Yes starts the node at boot, before you even sign in, and needs one administrator confirmation (which also sets up the firewall rules, in the same step — see below). No keeps the normal per-user mode: the node starts when you sign in, with no admin needed, and you can turn autostart on later from the Node page.
• (per-user mode only) "Allow MeshBay through Windows Firewall now?" — one administrator confirmation adds the inbound rules the client and the node need for WebRTC and casting. Declining is fine — Windows shows its own "Allow access" dialog instead, the first time each is actually used.

Running setup again (an upgrade, a repair install) asks neither question if the firewall rules are already there.

ffmpeg — required for video streaming, bundled in the installer by default (verified, checksummed, GPLv3-licensed; LICENSE-ffmpeg.txt ships alongside it). Nothing to install separately.

First run

Open MeshBay and sign in. Use the Node page (or a terminal) to provision:

meshbay-node init
meshbay-node autostart install     # per-user mode: run at every sign-in (no admin)
meshbay-node service install       # service mode: run at boot (needs an elevated prompt)

The Node page's Start/Stop/Restart buttons work the same either way — they drive the Scheduled Task when service mode is active, or the daemon process directly otherwise.

Runtime data — node.toml, keystore.enc, unlock.key, data\ — lives in %LOCALAPPDATA%\meshbay\ and survives uninstall/reinstall, in either mode (service mode runs as your own account too — never LocalSystem — so nothing about where your data lives changes).

Uninstall

Apps & features → MeshBay → Uninstall, or the Start-menu Uninstall MeshBay entry. It stops a running daemon and removes the sign-in launcher; it offers (opt-in, one admin confirmation) to also remove the firewall rules and the boot-time service task, if you set one up. None of this touches %LOCALAPPDATA%\meshbay\ (the keystore).

Build from source

See packaging/win/README.md. On a machine with Node ≥ 22 and Python ≥ 3.12:

cd packages\meshbay-client
npm run dist:win

Post-install: Node (desktop user)

1. Initialize

meshbay-node init

This creates ~/.config/meshbay/ with a default config and environment (including the TMDB API token for the Videos app).

2. Create or join a group

meshbay-node group add --hub https://meshbay.org --upload-dir ~/Shared

Follow the interactive wizard to create a new group or accept an invitation.

3. Start the service

systemctl --user enable --now meshbay-node
loginctl enable-linger $USER    # keep serving when logged out

4. Launch the desktop app

Open MeshBay from the applications menu, or:

meshbay

Post-install: Hub (server)

1. Set up PostgreSQL

sudo -u postgres createuser meshbay
sudo -u postgres createdb -O meshbay meshbay_hub

2. Generate the hub keypair

sudo meshbay-hub --generate-keys

This writes /etc/meshbay/hub_private.pem.

3. Configure

sudo cp /opt/meshbay-hub/share/hub.toml.example /etc/meshbay/hub.toml
sudo nano /etc/meshbay/hub.toml

Edit at minimum: the database URL and the listen address.

Set the database password in /etc/meshbay/hub.env:

echo 'MESHBAY_DATABASE_URL=postgresql+asyncpg://meshbay:YOUR_PASSWORD@localhost/meshbay_hub' \
  | sudo tee /etc/meshbay/hub.env
sudo chmod 640 /etc/meshbay/hub.env
sudo chown meshbay:meshbay /etc/meshbay/hub.env

4. Start

sudo systemctl enable --now meshbay-hub
sudo journalctl -u meshbay-hub -f       # check logs

Firewall

The packages ship passive firewall profiles (not auto-activated).

Chromecast / Smart TV casting (client)

Opens TCP 19550-19553 (HTTP relay) and UDP 5353 (mDNS discovery).

# Fedora (firewalld)
sudo firewall-cmd --permanent --add-service=meshbay-cast
sudo firewall-cmd --reload

# Ubuntu (ufw)
sudo ufw allow "MeshBay Cast"

Peer connections (node)

Opens inbound UDP 1024-65535. Scope it to the LAN — apply the firewalld service to the zone holding the LAN interface, and give the ufw rule a from. It does not belong in an internet-facing zone.

# Fedora (firewalld) — replace FedoraWorkstation with your LAN zone
sudo firewall-cmd --permanent --zone=FedoraWorkstation --add-service=meshbay-node
sudo firewall-cmd --reload

# Ubuntu (ufw)
sudo ufw allow from 192.168.1.0/24 app "MeshBay Node"

# a libvirt guest reaching the node on its own hypervisor: scope to the guest
# subnet, since traffic to the host's own address is not masqueraded
sudo ufw allow in on virbr0 from 192.168.200.0/24 app "MeshBay Node"

Why a node needs this. WebRTC binds an ephemeral UDP port per connection, so there is no fixed port to open. A connection succeeds if either side can initiate. Browsers publish their host candidate as an mDNS <uuid>.local name, which aioice cannot resolve on any platform and discards — so the node can never call a browser back, and the browser must call the node. A node that refuses unsolicited inbound UDP is unreachable from every browser on its own LAN, and falls back to reflexive candidates, which fail whenever both peers share one public IP and the router will not hairpin.

The node's administration surface is unaffected: loopback only, see below.

The node's own administration surface is a loopback API (127.0.0.1 only, per-run token) reached by the CLI and the desktop client's Node page. It is never network-exposed and ships no firewall profile.

Building packages from source

On the target machine, from the repo checkout:

# Ubuntu / Debian
bash packaging/build/build-packages.sh deb

# Fedora
bash packaging/build/build-packages.sh rpm

Packages are written to /tmp/meshbay-build/out/.

Requirements: Python 3.12+, Node.js 22+ (for client), ImageMagick (for icon resizing), dpkg-deb or rpmbuild.