Your first mesh,
in five minutes.

A Linux laptop and an Android phone on one private network: one command, one app, one invite between them. Then ssh laptop.mesh from the phone works from anywhere — café wifi, mobile data, another country.

No account to create. No server to run. Nothing to pay for.

What you need

A Linux machine with systemd and docker or podman — a laptop, a desktop, a home server or a VPS — and root on it.
An Android phone (8 or newer, arm64) with F-Droid.
Five minutes. Most of the waiting is a node joining the gossip network, about twenty seconds.

1 · The laptop: create the mesh

Fetch the installer (read it if you like: it is plain shell, and this is it):

curl -fsSLO https://raw.githubusercontent.com/vpavlin/shrooms/master/scripts/install.sh

Create a mesh called home, with this machine called laptop:
```
sudo bash install.sh init --mesh home --name laptop
```
It asks for a passphrase for the admin key — the key that admits devices — and prints a recovery key once. Write that down somewhere that is not this laptop. Losing the laptop then costs the laptop, not the mesh.

If a firewall is on, open the port (laptops too — a closed port looks like everything except a closed port):

sudo ufw allow 51820/udp   # Ubuntu, Debian
sudo firewall-cmd --add-port=51820/udp --permanent && sudo firewall-cmd --reload   # Fedora

2 · The phone: install the app

In F-Droid: Settings → Repositories → +, and add
```
https://apps.vpavlin.xyz/fdroid/repo
```
Install Shrooms from that repository and open it. It opens on a join screen with one field and a scan button.

3 · Invite the phone

On the laptop:

sudo shrooms invite
Invite valid for 15m0s. On the joining device:
  shrooms join BEGUZ-N4WOX-PYMTR-CYKWT-QBYSX-U
  [QR code]
Waiting.

On the phone: scan the QR (or paste the token), name the phone, tap Join. Keep both screens open until it says it joined — an invite is answered live, once, by the machine that made it.
Allow the VPN when Android asks. The phone's roster fills with laptop, and the laptop's with the phone.

4 · Check it

sudo shrooms status
network  fd48:d107:3fce::/48                     peers 1 (1 up)
self     laptop  fd48:d107:3fce:2b84:226b:ac:f2c3:9f30
NAME    OVERLAY IP                               ANNOUNCE  TUNNEL  ENDPOINT
phone   fd48:d107:3fce:9d1c:7b2e:41a:cc90:1f22   online    up 31s  192.168.1.23:51820
ping6 phone.mesh

That is the mesh. Both devices have a stable address that is theirs on any network, and a name under .mesh. Turn off the phone's wifi and the tunnel follows it onto mobile data.

The laptop also serves Prometheus metrics on its mesh address, port 9180: tunnels, delivery, interfaces. Metrics has the dashboard.

When both ends are behind NAT — the phone on mobile data, the laptop on café wifi — they need one reachable member to meet through. A cheap VPS is the usual answer: install it with sudo bash install.sh prepare --name vps --relay and invite it like the phone. Relays and reachability has the details, including relays somebody else runs.

5 · More devices, and the desktop

Another Linux machine

sudo bash install.sh prepare --name nas, then sudo shrooms invite on the laptop and sudo shrooms join TOKEN on the newcomer.

The desktop app

Shrooms in Logos Basecamp: the graph, the roster, every setting, and — with a Keycard — inviting devices without a terminal.

Services by name

http://immich.nas.mesh instead of a port number, and ports bound only to the mesh.

Your coding agents

The Claude Code sessions on your machines, on your phone — over the mesh you just made.

If it does not connect

The phone never appears. The invite expired (fifteen minutes) or the laptop's shrooms invite was closed before the phone answered. Run it again.
Both show online, no tunnel. Almost always the firewall: open the port as in step 1. Then sudo shrooms status again.
Works at home, not outside. Two devices behind NAT need a reachable member: the VPS in the note above.
Everything else: when it does not work, and the phone's share diagnostics button, which produces a report worth pasting into an issue.

An experiment, with no guarantees. It is used daily by its author. Its one outside audit, in October 2026, was by an AI auditing agent rather than a security firm, and its findings are being fixed. SECURITY.md says what it protects and what it does not.