Install it once,
then admit
the next device.

• docker or podman, and systemd
• /dev/net/tun present
• root on the machine

Two peers need at least one of them reachable. A laptop with a default-deny firewall cannot be reached by a phone on the same wifi, so both ends announce perfectly good addresses, see each other as online, and fail every handshake — which looks like almost anything except a closed port.

The installer prints the right command for whichever firewall it finds running, and says nothing when none is.

After prepare:

==> checking this machine
==> fetching ghcr.io/vpavlin/shrooms:latest
==> generating config (prepare)
==> installing the service

Installed and running, waiting for a mesh.

On a machine already on one:
  shrooms invite

and back here:
  sudo shrooms join <TOKEN> --name nas

After init the same three lines, and then the mesh itself — network key, admin key, and the recovery key printed once. That output is in The first mesh.

Three verbs. init creates a mesh, join <NETWORK-KEY> joins one you have the key for, and prepare installs and starts the daemon with no mesh at all. prepare is the one to pair with invites — a daemon without a mesh still holds its control socket and waits to be told which network it is on, which is exactly what shrooms join needs it to be doing.

Everything after the verb is handed to shrooms unchanged — --name, --relay, --advertise, --port — so the script cannot drift out of date with the flags the binary supports. The device name defaults to this machine's hostname.

Nothing is built on the box. The container carries the binary and liblogosdelivery, which needs glibc 2.38 and exists only where Logos Basecamp is installed, so shipping an image rather than a tarball is what makes a Debian 12 machine work at all. It runs with host networking on purpose: behind docker's bridge the address peers observe would be the gateway's and the source port would be rewritten, so traversal would be fighting a layer of NAT that does not exist in reality.

It touches /etc/shrooms/ (config), /var/lib/shrooms/ (device identity), /run/shrooms/ (control socket), a shrooms systemd unit and container, a shrooms-resolved unit that registers mesh names with the host's resolver, and /usr/local/bin/shrooms — a wrapper so shrooms status works on the host without anyone remembering the docker incantation. It runs docker exec -i, with a stdin, so the commands that prompt work through it. Under sudo on a podman host: the daemon's container is root's, and a rootless podman cannot see it.

With one exception, which is the whole reason the wrapper is more than one line. The commands that touch the mesh authority — init, invite, admin, keycard — read and write ~/.config/shrooms, and the daemon container has no such directory: its unit mounts the config, the state and the socket, and nothing of yours. So those run in a sibling container with your admin directory mounted, rather than inside the daemon's. The daemon is deliberately left without it: it verifies credentials and never signs one, and a process that cannot read a key cannot leak it (ADR-025).

Re-running is safe: an existing config and identity are left alone unless you pass --force. Losing the identity would mean a new overlay address and looking like a different device to every peer, so it is never destroyed by accident. On a SELinux host the bind mounts are relabelled shared, without which the daemon cannot bind its control socket and systemd restarts it forever.

Read the script before running it as root, as you should with anything fetched this way.

Worth it when you want the binary on the host rather than in a container — and it is what scripts/deploy.sh needs on the machine you drive a remote install from.

git clone https://github.com/vpavlin/shrooms && cd shrooms
make deps-release       # prebuilt liblogosdelivery; there is no distribution of it
make shrooms
sudo make install       # binary, libraries, systemd unit, bash completion

make install relinks the binary with an rpath pointing at /usr/local/lib/shrooms, so it keeps working after you delete the checkout. It needs Go 1.23+ with cgo and a C toolchain to build, and glibc 2.38 or newer to run — Debian 12 has 2.36 and will not do, which is the case the container exists for. make deps builds the library from source and currently fails on an upstream compile error; make deps-release downloads a repackaged copy instead, which is the one you want.

• an Android 8 or newer phone, arm64
• an F-Droid client installed
• an invite from a machine already on the mesh, or its network key

The app on the launcher, opening on a single join screen with one field. After joining, the roster fills with the same peers the daemon reports, and Android's VPN key appears in the status bar.

That F-Droid repository is self-hosted. There is no Google Play listing and there is not going to be one — the repository is the author's own, published alongside the other Logos modules on the same host, and adding it is a decision you are making about who you take software from.

arm64 only. There is no x86_64 build of the delivery library, so an emulator has no node and the app is a phone-shaped thing to test on a phone.

The app is a Compose UI and a VpnService around the same Go core as the daemon — nothing in internal/ is reimplemented. It joins several meshes at once and roams between wifi and mobile data without you touching it: direct on wifi, relayed on a carrier's CGNAT, and the transition survives in both directions. ANDROID.md is the build in detail, and ADR-016 is why it reuses the core rather than reimplementing it.

make apk                       # android/shrooms.apk, debug-signed
adb install -r android/shrooms.apk

make fdroid                    # build unsigned, sign on the repo host, publish

make apk needs the Android SDK and an NDK; it builds the .aar in a container first, because gomobile wants a JDK and a newer Go than the core deliberately does. make fdroid is the publishing half and only useful if you run a repository of your own: the signing key lives on that host and never leaves it, so the APK is built here unsigned and signed there.

• Logos Basecamp installed
• a shrooms daemon already running on this same machine
• socket_group set in /etc/shrooms/config.toml to a group you are in

Shrooms in Basecamp's app list, and opening it shows the same roster shrooms status prints in a terminal: peers, whether each is direct or relayed, throughput, and how long each took to connect. If the socket group is not set it says so, rather than showing an empty mesh.

It also changes things, which is the part that removes the terminal: this device's name, whether it runs the rendezvous plane as edge or core, what it publishes and whether those names and its bound ports are announced, whether it relays for a mesh, whether the router is asked for a way in, which meshes run, joining one with an invite token and leaving one — and restarting the daemon, which is what applies the settings that need it. Beside that: every device's services as addresses you can click, when each credential expires, and the daemon's own log, because Basecamp cannot read the journal.

Two packages, versioned separately: shrooms is the view and shrooms_core is the part that talks to the daemon. The view declares the dependency, so installing from the repository brings both. Fetching files by hand means fetching both, or you get an interface whose buttons do nothing.

The view reads the daemon through shrooms_core, a companion module installed alongside it. That indirection is not ceremony. A ui_qml app runs inside a sandbox where a deny-all network manager blocks every outgoing request and XMLHttpRequest refuses local files, so neither a status file nor a port is reachable from the view, whatever their permissions. A Logos module runs in its own process and is not sandboxed, which is the route Basecamp prescribes: it does one request over the daemon's control socket and hands back the JSON.

The socket group is a real grant, like docker's. Anyone in it can read your mesh's control plane and change this device's behaviour. Name a group you would trust with that — on a personal machine, your own login — and leave it unset on a shared one. The socket is 0660 and the daemon runs as root for CAP_NET_ADMIN, which is what makes the group half of that mean anything.

It can change what this device decides for itself: its name, relay or light node, published services, which meshes run, and leaving one. What it cannot do is admit anybody, and that is the line the design draws. Membership is a credential signed by an admin key the daemon has never held — a passphrase-protected file in your home directory — so nothing reachable through that socket can make a device a member or remove one. Admission stays with shrooms invite and a passphrase prompt, which is where the friction belongs. ADR-025 is the whole argument.

make basecamp-check     # load the real view offscreen against a fixture
make basecamp-lgx       # build the installable package
make basecamp-publish   # cut a GitHub release carrying it

basecamp-lgx builds the portable variant through nix, because the plain one can reference paths in the nix store of the machine that built it — fine for a dev loop and useless as a download. CI builds it on every push and uploads it as an artifact. basecamp-publish uploads two assets to a release: a versioned name so an install can be pinned, and the stable one linked above.

• a KVM VPS — OpenVZ and LXC hosts often have no /dev/net/tun, and it is worth checking before you pay
• docker or podman, and root
• one inbound UDP port, 51820 by default

Installed and running, waiting for a mesh.

A firewall is running here. Peers reach this node on UDP 51820, so open it:
  sudo ufw allow 51820/udp

Then redeem an invite from a machine already on the mesh. Resource use is negligible — a measured node acting as a relay sits at about 20 MiB RSS and one to two per cent of one core — so what matters on a VPS is bandwidth allowance and latency, since relayed traffic takes a detour through it.

A node behind NAT learns its own public address by reflection: a peer's reply echoes the address that peer observed. That needs a peer outside your NAT. On a mesh whose members are all behind one router, no node can learn its public address at all, every candidate it announces is a LAN address, and the mesh works from the sofa and not from the street. One reachable member is the anchor that fixes this — and, being reachable, it is also what can relay for two peers that cannot reach each other directly.

You probably do not need a VPS. Any node with a reachable address can relay: set relay = "true" in its config and restart it. Nothing else needs configuring — the relay advertises itself in its ordinary announce and every other node picks it up, so there are no relay addresses to distribute and its IP can change freely. An office box with a port forward or a home server on a static address covers every pair that cannot connect directly.

A node will also ask the router for a way in — PCP first, then NAT-PMP, both on the gateway's UDP 5351. That is on by default (port_mapping), and a laptop behind a domestic NAT has been granted a mapping, announced it, and been dialled directly by a phone on mobile data, on a mesh with no publicly reachable member at all. Whether your router answers is between you and your router; when it does not, nothing is worse than before.

Two things it does not fix. Carrier-grade NAT can be neither punched nor mapped, so a phone on mobile data needs a relay somewhere in the mesh. And punching between two NATed peers is still unproven — a reachable member is what makes the awkward cases work today. ADR-012 covers who should host one.

scripts/deploy.sh is the alternative when you have the repository checked out and would rather not type on the remote at all. It wants docker on the far side rather than podman, and a built ./bin/shrooms here.

./scripts/deploy.sh root@VPS_IP --relay --name vps --key <NETWORK-KEY>
./scripts/deploy.sh root@VPS_IP --init --relay --name vps   # or create the mesh

With --init the config is generated locally, by your own binary, and only then copied over — which is why the passphrase prompt works and why the admin key stays on your machine rather than on the VPS. The config travels over ssh stdin and lands with install -m600, so the network key is never readable at a predictable path in the remote's /tmp. The remote generates its own device identity, so no private key crosses the wire. It refuses to overwrite an existing config without --force, pulls the published image on the remote by default, and builds from your working tree when you set BUILD_IMAGE=1.