Shrooms: Difference between revisions

Revision as of 21:01, 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 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.

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.
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.
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.
It answers names such as laptop.mesh and immich.home-server.mesh with its own resolver, and 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.
It runs several meshes from one daemon, 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.
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.

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.

Use it

On the first Linux machine, download scripts/install.sh from the repository and run sudo bash install.sh init --mesh home --name laptop. The README asks users to read the script before running it as root.
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 glibc (the standard C library) 2.38 or later. Ubuntu 24.04 works and Debian 12 does not. Every node needs /dev/net/tun (a virtual network device). 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 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 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.
 == What it does ==
-* Lets nodes find each other through Logos Delivery pub/sub, 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 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.
-* Carries traffic over userspace WireGuard, directly between peers where NAT allows. When two peers cannot reach each other, it relays through a node the user already runs.
+* 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.
-* Derives each node's overlay address from its device key, so no addresses are handed out and none conflict.
+* 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.
-* 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.
+* 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.
-* Admits devices with one-time invite tokens and admin-signed credentials that expire after 30 days by default and can be revoked.
+* It admits devices with one-time invite tokens and admin-signed credentials that expire after 30 days by default and can be revoked.
-* Runs several meshes from one daemon, each with its own key, identity, interface and port.
+* It runs several meshes from one daemon, each with its own key, identity, interface and port.
-* Shows the mesh in a Basecamp view with a graph, peers, services, logs and settings.
+* It shows the mesh in a Basecamp view with a graph, peers, services, logs and settings.
-* 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.
+* 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.
 The project was renamed from logos-vpn.
-Stage: Prototype. The README says "It is a prototype, used daily by its author and nobody else." It opens with "This is an experiment, and there are no guarantees of any kind." and says it "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." It also says the project "has never been audited by anybody independent". The README does not say whether it is an official Logos project.
 == Use it ==
@@ Line 31: / Line 31: @@
 # 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 needs glibc 2.38 or later (Ubuntu 24.04 works, Debian 12 does not), <code>/dev/net/tun</code>, and one 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 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.
 == Build it ==
@@ Line 46: / Line 46: @@
 * [[Tools]]
 * [[Logos Messaging]]
-* [[Reelcut]]
+* [[Reelcut]]: also by vpavlin
 == Sources ==
@@ Line 52: / Line 52: @@
 * [https://github.com/vpavlin/shrooms/blob/master/basecamp/metadata.json basecamp/metadata.json], [https://github.com/vpavlin/shrooms/blob/master/basecamp/core/metadata.json basecamp/core/metadata.json] and [https://github.com/vpavlin/shrooms/blob/master/basecamp-agents/metadata.json basecamp-agents/metadata.json], GitHub
 * [https://github.com/vpavlin/shrooms/tags shrooms tags], GitHub
+* [https://github.com/vpavlin/shrooms/blob/master/scripts/install.sh scripts/install.sh], GitHub
 {{Page status|Stub}}