MeshVPN

A lightweight, peer-to-peer mesh VPN implementation built with WireGuard, ICE (Interactive Connectivity Establishment), and HTTP signaling. MeshVPN enables secure, decentralized mesh network connections without relying on centralized VPN providers.

Overview

MeshVPN combines industry-standard technologies to create a simple yet functional mesh networking solution:

• WireGuard: Fast, modern cryptography-based VPN protocol
• ICE Protocol: NAT traversal for peer discovery and connection establishment
• HTTP Signaling: Simple, scalable signaling server for peer coordination
• Cross-Platform: Native support for Linux and Windows

This project demonstrates core networking concepts including tunnel device creation, peer-to-peer communication, and distributed mesh architecture.

Architecture

MeshVPN Components:
├── Client (meshvpn)
│   ├── TUN Device Management
│   ├── ICE Agent (P2P negotiation)
│   ├── WireGuard Interface
│   └── Peer Management
└── Signaling Server (meshvpnss)
    └── Message Broker (client coordination)

Quick Start

Prerequisites

• Go 1.25+
• Linux: Root privileges (for TUN device creation)
• Windows: WinTun driver compatibility

Installation

git clone https://github.com/MiZuii/MeshVPN.git
cd MeshVPN
make

Building for Specific Platforms

# Linux binaries
make linux-client linux-server

# Windows binaries (from Linux)
make windows-client windows-server

# Current OS binaries
make all

Running

Start the Signaling Server

./bin/meshvpnss

The server runs on localhost:80 by default. For internet-facing deployment, use a reverse proxy like ngrok:

ngrok http 80

Start Clients

Each client connects to the mesh network with a unique ID:

# Client 1
./bin/meshvpn -id=1 -signaling="http://your-signaling-server:80" -name="meshvpn0"

# Client 2
./bin/meshvpn -id=2 -signaling="http://your-signaling-server:80" -name="meshvpn1"

Configuration Options

Option	Description	Example
-id	Unique client ID (1-254, also determines virtual IP suffix)	-id=1 (IP: 10.0.0.1)
-signaling	Signaling server URL	-signaling="http://localhost:80"
-name	Virtual network interface name	-name="meshvpn0"

Project Structure

.
├── cmd/
│   ├── client/        # VPN client implementation
│   └── signal/        # HTTP signaling server
├── internal/
│   ├── ice/           # ICE protocol implementation & peer management
│   ├── multiplex/     # WireGuard binding & multiplexing
│   ├── signaling/     # Message protocol definitions
│   └── tun/           # TUN device interface (cross-platform)
├── go.mod             # Go dependencies
└── makefile           # Build targets

Development

Build Commands

# Build all
make all

# Run with defaults
make run-client
make run-server

# Clean build artifacts
make clean

Technologies Used

• Go: Core implementation language
• WireGuard: Cryptographic VPN protocol
• Pion ICE: WebRTC-compatible ICE implementation
• netlink: Linux network interface management
• wintun: Windows tunnel device API

Use Cases

• Learning mesh networking and VPN technologies
• Prototyping P2P applications
• Educational reference for WireGuard and ICE integration
• Testing distributed network concepts

Testing

Automated End-to-End Tests

Run the automated test suite to validate the entire mesh network setup:

# Run end-to-end tests (requires root for TUN device creation)
sudo python3 tests/e2e_test.py

The test suite validates:

• ✓ Signaling server startup
• ✓ Client initialization (multiple instances)
• ✓ Virtual network interface creation
• ✓ IP address assignment
• ✓ Process health and stability

Data Transfer Tests

Test actual data transmission over the mesh network:

# Run data transfer tests (requires root)
sudo python3 tests/data_transfer_test.py

The data transfer test suite includes:

• ✓ Ping connectivity between clients
• ✓ TCP connection establishment and small data transfer
• ✓ Large data transfer (1MB) with integrity verification

Manual Testing

For manual testing with multiple clients:

# Terminal 1 - Signaling server
./bin/meshvpnss

# Terminal 2 - Client 1
./bin/meshvpn -id=1 -name="meshvpn0"

# Terminal 3 - Client 2
./bin/meshvpn -id=2 -name="meshvpn1"

Test connectivity manually with netcat:

# On Client 1 terminal: start a listening server
nc -v -l <client 1 IP> 8888

# On Client 2 terminal: connect and send data
nc -v -s <client 2 IP> <client 1 IP> 8888

Disclaimer

This is an educational project to learn the basics. For production ready solutions check out other numerous mesh VPNs.