Getting Started

Install

Linux

curl -fsSL https://raw.githubusercontent.com/igorls/meshguard/main/install.sh | bash

This will:

• Detect your architecture (x86_64 / arm64)
• Install libsodium if needed by the selected release artifact
• Download the latest release from GitHub Releases
• Install to /usr/local/bin/meshguard

Windows

irm https://raw.githubusercontent.com/igorls/meshguard/main/install.ps1 | iex

This will:

• Download meshguard.exe and wintun.dll from the latest release
• Install to %LOCALAPPDATA%\meshguard\
• Add to your user PATH

Manual download

You can also download binaries directly from the releases page.

Building from source

Alternatively, build from source with Zig 0.16+:

Target	Notes
Linux	Kernel or userspace mode; libsodium is an optional AVX2 accelerator on amd64
macOS	Userspace mode via utun; uses std.crypto
FreeBSD	Userspace mode via tun(4); uses std.crypto
Windows	Userspace mode via Wintun; requires Administrator for meshguard up
Android / iOS	FFI library only; no TUN interface from the CLI

# Debug build
zig build

# Optimized static binary
zig build -Doptimize=ReleaseFast

# Linux arm64 without libsodium
zig build -Dtarget=aarch64-linux-gnu -Doptimize=ReleaseFast -Dno-sodium=true

# macOS, FreeBSD, and Windows release targets
zig build -Dtarget=aarch64-macos -Doptimize=ReleaseFast
zig build -Dtarget=x86_64-freebsd -Doptimize=ReleaseFast
zig build -Dtarget=x86_64-windows -Doptimize=ReleaseFast

# Run test suite
zig build test

The output binary is placed at zig-out/bin/meshguard.

Quick Start

1. Generate an identity

Every meshguard node needs an Ed25519 keypair. Generate one:

meshguard keygen

This creates two files in your config directory:

• Linux: ~/.config/meshguard/ (or /etc/meshguard/ as root)
• Windows: %APPDATA%\meshguard\

File	Contents
identity.key	Base64-encoded Ed25519 secret key (0600)
identity.pub	Base64-encoded Ed25519 public key

TIP

Running keygen again will not overwrite existing keys. Use --force to regenerate:

meshguard keygen --force

2. Export your public key

meshguard export > my-node.pub

Share my-node.pub with every node that should trust you.

3. Trust a peer

# From a .pub file
meshguard trust /path/to/peer.pub

# From a raw base64 key
meshguard trust "dGhpcyBpcyBhIHNhbXBsZSBrZXkgZm9yIGRvYw=="

# With a human-readable label
meshguard trust /path/to/peer.pub --name validator-3

The key is stored in ~/.config/meshguard/authorized_keys/<name>.pub.

4. Join the mesh

# With at least one seed peer
meshguard up --seed 1.2.3.4:51821

# Multiple seeds
meshguard up --seed 1.2.3.4:51821 --seed 5.6.7.8:51821

# With a manually announced public IP
meshguard up --seed 1.2.3.4:51821 --announce 203.0.113.42

# Kernel WireGuard mode (default is userspace)
meshguard up --seed 1.2.3.4:51821 --kernel

# Discovery/rendezvous only, no TUN interface
meshguard up --gossip-only --seed 1.2.3.4:51821

meshguard will:

1. Load your identity from ~/.config/meshguard/
2. Derive your deterministic mesh IP (10.99.X.Y)
3. Create the mg0 WireGuard interface unless --gossip-only is used
4. Run STUN to discover your public endpoint
5. Begin gossiping with seed peers via the SWIM protocol
6. Automatically configure WireGuard tunnels as peers are discovered

5. Stop the daemon

meshguard down

When a userspace daemon is running, this requests a graceful shutdown through the control socket. On Linux, if no daemon control socket answers, it falls back to removing the kernel mg0 interface.

6. Check status

meshguard status

When a userspace daemon is running, this reports the node public key, mesh IP, and membership counts from the control socket. On Linux, if no control socket answers, it falls back to kernel mg0 status where available.

Run as a service

The installer automatically sets up a systemd service. To use it:

# Configure seed peers
sudo vi /etc/default/meshguard

# Enable and start
sudo systemctl enable meshguard
sudo systemctl start meshguard

# View logs
sudo journalctl -u meshguard -f

Edit /etc/default/meshguard to set your options:

# Seed peers and flags
MESHGUARD_OPTS="--seed 1.2.3.4:51821"