Shrooms: Difference between revisions

Latest revision as of 23:27, 4 November 2026

Shrooms

What it does: The mycelial mesh VPN: discovery over Logos Delivery, traffic over WireGuard, no coordination server

Stage: Prototype

Licence: Apache-2.0 or MIT

Verified on 4 November 2026 against README and commit of 4 November 2026.

Shrooms is a mesh VPN by the GitHub user vpavlin that uses Logos Messaging (Logos Delivery) for discovery and signalling and WireGuard, a standard VPN protocol, for the traffic. It has a Linux daemon, an Android app and a Basecamp view, and was renamed from logos-vpn.

What it does

Nodes find each other through Logos Delivery pub/sub (publish-and-subscribe messaging), with no coordination server and no account. Delivery is used only for cold start, roaming and repair, and tunnels keep working when the fleet is unreachable.
Traffic runs over userspace WireGuard, directly between peers where NAT allows. NAT is the way home routers and mobile networks hide many devices behind one address. When two peers cannot reach each other, Shrooms relays through a node the user already runs.
Each node's overlay address, its address inside the mesh, is derived from its device key, so no addresses are handed out and none conflict.
Its own resolver answers names such as laptop.mesh and immich.home-server.mesh, and it can publish local services and LAN devices by name.
Devices are admitted with one-time invite tokens and admin-signed credentials, which expire after 30 days by default and can be revoked.
One daemon runs several meshes, each with its own key, identity, interface and port.
A Basecamp view shows the mesh with a graph, peers, services, logs and settings.
Shrooms Agents, a separate app and Basecamp module, reaches Claude Code or pi coding-agent sessions on the user's own machines from a phone or from Basecamp.

Stage: Prototype. The README says "It is a prototype, used daily by its author and nobody else." Its opening warning reads "This is an experiment, and there are no guarantees of any kind", and it says the project has never been audited by anybody independent. The README does not say whether it is an official Logos project.

Use it

On the first Linux machine, download scripts/install.sh from the repository and read it before running it as root with sudo bash install.sh init --mesh home --name laptop.
Run sudo shrooms invite. It prints a token and a QR code, good for one device and fifteen minutes, and waits.
On the new device, run sudo shrooms join TOKEN with the printed token, or scan the QR code with the Android app.
For Android, add https://apps.vpavlin.xyz/fdroid/repo to F-Droid and install Shrooms, and Shrooms Agents if wanted.
For Basecamp, add https://apps.vpavlin.xyz/basecamp/logos-repo.json and install Shrooms. Its shrooms_core companion comes with it.

A Linux node run outside the container needs version 2.38 or later of glibc, the standard C library. Ubuntu 24.04 works and Debian 12 does not. Every node needs /dev/net/tun, a virtual network device, and at least one end of every pair of nodes needs an inbound UDP port, 51820 by default. A five-minute quick start is on the project website. The README does not name a Basecamp version.

Build it

The build machine needs Go 1.26 or later with cgo and a C toolchain, and liblogosdelivery. make deps-release downloads a prebuilt copy of the library.
make shrooms builds the binary and sudo make install installs it with a systemd unit.
make dist and make dist-arm64 build portable packages. scripts/deploy.sh builds a container image and ships it to a host over ssh.
make apk builds the Android app (details in ANDROID.md) and make basecamp-lgx builds the Basecamp package.

Releases

The latest version tag is v0.9.0, dated 21 September 2026. Two later tags, deps-v2 (20 October 2026) and deps-v3 (23 October 2026), are dependency releases. The README links deps-v1 as a repackaged copy of liblogosdelivery. In metadata.json, the Basecamp view shrooms is version 0.14.0, shrooms_core is 0.29.0 and shrooms_agents is 0.59.0.

Sources

shrooms README, GitHub, last commit 4 November 2026
basecamp/metadata.json, basecamp/core/metadata.json and basecamp-agents/metadata.json, GitHub
shrooms tags, GitHub
scripts/install.sh, GitHub

Page status: Stub. Stub · Outline · Usable · Guide · Star. Anyone can improve this page and change its status.

@@ Line 10: / Line 10: @@
 | verified_against = README and commit of 4 November 2026
 }}
-'''Shrooms''' is a mesh VPN that uses [[Logos Messaging]] (Logos Delivery) for discovery and signalling and WireGuard, a standard VPN protocol, for the traffic. It has a Linux daemon, an Android app and a [[Basecamp]] view, and is published by the GitHub user vpavlin.
+'''Shrooms''' is a mesh VPN by the GitHub user vpavlin that uses [[Logos Messaging]] (Logos Delivery) for discovery and signalling and WireGuard, a standard VPN protocol, for the traffic. It has a Linux daemon, an Android app and a [[Basecamp]] view, and was renamed from logos-vpn.
 == What it does ==
-* It lets nodes find each other through Logos Delivery pub/sub (publish-and-subscribe messaging), with no coordination server and no account. Delivery is used only for cold start, roaming and repair, and tunnels keep working when the fleet is unreachable.
+* Nodes find each other through Logos Delivery pub/sub (publish-and-subscribe messaging), with no coordination server and no account. Delivery is used only for cold start, roaming and repair, and tunnels keep working when the fleet is unreachable.
-* It carries traffic over userspace WireGuard, directly between peers where NAT allows. NAT is the way home routers and mobile networks hide many devices behind one address. When two peers cannot reach each other, it relays through a node the user already runs.
+* Traffic runs over userspace WireGuard, directly between peers where NAT allows. NAT is the way home routers and mobile networks hide many devices behind one address. When two peers cannot reach each other, Shrooms relays through a node the user already runs.
-* It derives each node's overlay address (its address inside the mesh) from its device key, so no addresses are handed out and none conflict.
+* Each node's overlay address, its address inside the mesh, is derived from its device key, so no addresses are handed out and none conflict.
-* It answers names such as <code>laptop.mesh</code> and <code>immich.home-server.mesh</code> with its own resolver, and can publish local services and LAN devices by name.
+* Its own resolver answers names such as <code>laptop.mesh</code> and <code>immich.home-server.mesh</code>, and it can publish local services and LAN devices by name.
-* It admits devices with one-time invite tokens and admin-signed credentials that expire after 30 days by default and can be revoked.
+* Devices are admitted with one-time invite tokens and admin-signed credentials, which expire after 30 days by default and can be revoked.
-* It runs several meshes from one daemon, each with its own key, identity, interface and port.
+* One daemon runs several meshes, each with its own key, identity, interface and port.
-* It shows the mesh in a Basecamp view with a graph, peers, services, logs and settings.
+* A Basecamp view shows the mesh with a graph, peers, services, logs and settings.
-* It offers Shrooms Agents, a separate app and Basecamp module for reaching Claude Code or pi coding-agent sessions on the user's own machines from a phone or from Basecamp.
+* Shrooms Agents, a separate app and Basecamp module, reaches Claude Code or pi coding-agent sessions on the user's own machines from a phone or from Basecamp.
-The project was renamed from logos-vpn.
-Stage: Prototype. The README says "It is a prototype, used daily by its author and nobody else." Its opening warning reads "This is an experiment, and there are no guarantees of any kind." It also says the project "has never been audited by anybody independent". The README does not say whether it is an official Logos project.
+Stage: Prototype. The README says "It is a prototype, used daily by its author and nobody else." Its opening warning reads "This is an experiment, and there are no guarantees of any kind", and it says the project has never been audited by anybody independent. The README does not say whether it is an official Logos project.
 == Use it ==
-# On the first Linux machine, download <code>scripts/install.sh</code> from the repository and run <code>sudo bash install.sh init --mesh home --name laptop</code>. The README asks users to read the script before running it as root.
+# On the first Linux machine, download <code>scripts/install.sh</code> from the repository and read it before running it as root with <code>sudo bash install.sh init --mesh home --name laptop</code>.
 # Run <code>sudo shrooms invite</code>. It prints a token and a QR code, good for one device and fifteen minutes, and waits.
 # On the new device, run <code>sudo shrooms join TOKEN</code> with the printed token, or scan the QR code with the Android app.
 # For Android, add <code>https://apps.vpavlin.xyz/fdroid/repo</code> to F-Droid and install Shrooms, and Shrooms Agents if wanted.
 # For Basecamp, add <code>https://apps.vpavlin.xyz/basecamp/logos-repo.json</code> and install Shrooms. Its <code>shrooms_core</code> companion comes with it.
-A Linux node run outside the container needs glibc (the standard C library) 2.38 or later. Ubuntu 24.04 works and Debian 12 does not. Every node needs <code>/dev/net/tun</code> (a virtual network device). At least one end of every pair of nodes needs an inbound UDP port, 51820 by default. A five-minute [https://shrooms.vpavlin.xyz/start.html quick start] is on the project website. The README does not name a Basecamp version.
+A Linux node run outside the container needs version 2.38 or later of glibc, the standard C library. Ubuntu 24.04 works and Debian 12 does not. Every node needs <code>/dev/net/tun</code>, a virtual network device, and at least one end of every pair of nodes needs an inbound UDP port, 51820 by default. A five-minute [https://shrooms.vpavlin.xyz/start.html quick start] is on the project website. The README does not name a Basecamp version.
 == Build it ==