meshvpn

Get started · 5 minutes

Your first network

Connect a few machines into one private network. Every machine gets a fixed address and a name like pi.mesh, wherever it is.

You need: two or more machines, root on eachWorks on: Linux, macOS, Windows 10/11

STEP 1

Install meshvpn

On Linux and macOS one command installs the static binary:

Linux, macOS
$ curl -fsSL https://github.com/PlugOvr-ai/meshvpn/releases/latest/download/install.sh | sudo sh

On Windows, in PowerShell as administrator:

Windows
PS> irm https://github.com/PlugOvr-ai/meshvpn/releases/latest/download/install.ps1 | iex

Packages, other platforms and how to check a download by hand: Download.

STEP 2

Create the network

Start on the machine that is easiest to reach: a server with a public address, or simply your desktop at home. It is not special to meshvpn, only a good first contact for the others.

$ sudo meshvpn init --network home --endpoint my-server.example.com:7870
$ sudo meshvpn install       # runs as a service, also after a reboot

--endpoint is where others can reach it; leave it out for a machine at home (see step 5). init prints an invite code. Treat it like a password: it lets one new machine in, within 24 hours.

STEP 3

Add machines

On every other machine, with an invite code (make more with sudo meshvpn invite):

$ sudo meshvpn join mesh1-eyJuZXR3b3Jr...
$ sudo meshvpn install
$ meshvpn status
● laptop  100.122.64.143  (network "home")

NAME     IP               STATUS   RTT   PATH
server   100.94.140.208   online   12ms  direct my-server.example.com:7870
Install and join at once: curl -fsSL …/install.sh | sudo sh -s -- join mesh1-...

STEP 4

SSH between nodes

Decide who may log in where, in one grid, then log in by name, without passwords:

$ sudo meshvpn ssh            # on the machine you want to log in to
$ ssh server.mesh

Also try meshvpn exec tag:gpu nvidia-smi, meshvpn cp, meshvpn desktop server and meshvpn console.

STEP 5

No server at all: a home router and a laptop on 5G

You don't need a server with a fixed address. A desktop behind a home router and a laptop on a phone's hotspot can find each other every day, after every new address:

  • The router opens the port. A node behind a home router opens its port 7870 with UPnP, NAT-PMP or PCP by itself. On a FRITZ!Box, allow it once for that device (Internet › Freigaben › Portfreigaben › Gerät › Selbstständige Portfreigaben erlauben).
  • Hole punching over IPv6. Where no port can be opened (mobile networks, DS-Lite), two nodes with IPv6 punch through to each other.
  • The rendezvous finds the new address. Switch the DHT on, on both machines: add dht = true at the top of the configuration, before any [section].
$ sudoedit /etc/meshvpn/config.toml   # add: dht = true
$ sudo systemctl restart meshvpn       # macOS: sudo launchctl kickstart -k system/ai.plugovr.meshvpn
$ meshvpn status
rendezvous: DHT, published …

Invites made with the DHT on also let a new machine join this way, even when neither side can reach the other.

Company networks: the DHT is off by default because firewalls there may take it for BitTorrent. Leave it off on a work notebook, and punch = false if repeated connection attempts to home addresses would stand out.

Two machines that both only have IPv4 behind carrier-grade NAT still need a third node with a public address, for example a small VPS or a free cloud VM.

STEP 6

Check and update

$ meshvpn doctor              # checks the setup, says what to fix
$ meshvpn net why laptop      # why there's no direct path to a node
$ sudo meshvpn update         # the newest release, if its signature verifies

Everything else, from exit nodes to distributed training: the README and the tutorial.