tunnelmesh

module

v0.0.0-...-308bc81 Latest Latest Go to latest Published: Mar 11, 2026 License: AGPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/tunnelmesh/tunnelmesh

Links

Open Source Insights

README ¶

Admin Dashboard

[!WARNING] Highly experimental: Stable but still tightening bolts. Not for Production use.

tunnelmesh

A peer-to-peer mesh networking tool that creates encrypted tunnels between nodes. tunnelmesh enables direct, secure communication between peers in a distributed topology without requiring a traditional VPN or centralised traffic routing.

Features

P2P Encrypted Tunnels - Direct connections between peers using pluggable transports
Coordinator Peers - Admin peers that provide discovery, IP allocation, and NAT traversal coordination
Exit Peers - Split-tunnel routing: route internet traffic through peers and keep mesh traffic direct
TUN Interface - Virtual network interface for transparent IP routing
Built-in DNS - Local resolver for mesh hostnames (e.g., node.tunnelmesh or node.tm)
Network Monitoring - Automatic detection of network changes with re-connection
Pluggable Transport Layer - Supports SSH, UDP, and WebSocket relay transports with fallback
NAT Traversal - UDP hole-punching with STUN-like endpoint discovery, plus relay fallback
Multi-Platform - Linux, macOS, and Windows support
Admin Dashboard - Web UI for mesh status, peers, traffic statistics, and per-peer transport controls
Node Location Map - Geographic visualisation of mesh peers
Unified Architecture - All nodes are peers; coordinators are peers with admin services enabled
High Performance - Zero-copy packet forwarding with lock-free routing table
Internal Packet Filter - Port-based firewall with per-peer rules, configurable via config, CLI, or admin UI
S3 Compatible Storage - Distributed and replicated across the mesh with erasure coding
Observability Baked-in - Prometheus, Grafana, Loki, and Grafana Tempo integrated into Admin dashboard with distributed tracing via OpenTelemetry (OTLP)

Architecture

tunnelmesh architecture

Key points:

Unified Architecture: All nodes are peers; coordinators are admin peers with services enabled
Traffic flows directly between peers via encrypted tunnels — UDP (ChaCha20-Poly1305), SSH, or WebSocket relay with automatic fallback
Coordinator peers handle discovery, registration, and NAT traversal coordination
Peers behind NAT use hole-punching or relay as fallback

Documentation

Full documentation is at read.tunnelmesh.io, covering:

Quick Start Guide — installation, setup, and first mesh
Admin Guide — coordinator config, admin interface, and mesh management
User Identity & RBAC — users, groups, and access control
CLI Reference — all commands, flags, and walkthroughs
Docker Deployment — containerised setup and multi-coordinator testing

Docker Deployment

Run tunnelmesh in containers for development, testing, or production. The docker-compose setup includes scalable coordinators for testing chunk-level replication between multiple coordinator nodes. See the Docker Deployment Guide for complete documentation.

cd docker
docker compose up -d                         # Start with 2 coordinators (default)
docker compose up -d --scale coordinator=3   # Scale to 3 coordinators
make docker-logs-coords                      # View coordinator logs
make docker-test                             # Run connectivity tests

Multi-coordinator features:

Coordinators discover each other via peer registration (no primary/replica distinction)
S3 chunks replicated peer-to-peer based on per-bucket replication factors
Each coordinator runs its own monitoring stack (Prometheus/Grafana/Loki/Tempo)
Ephemeral storage (tmpfs) for testing - data resets on restart
Easy scaling for replication testing: make docker-scale-coords

Cloud Deployment

Deploy to DigitalOcean App Platform with Terraform. See the Cloud Deployment Guide for complete documentation.

cd terraform
cp terraform.tfvars.example terraform.tfvars
export TF_VAR_do_token="dop_v1_xxx"
terraform init && terraform apply

Development

Running Tests

make test           # Run tests
make test-verbose   # Verbose output
make test-coverage  # With coverage report

Code Quality

make lint  # Run golangci-lint
make fmt   # Format code

Development Servers

make dev-server  # Build and run server
make dev-peer    # Build and run peer (with sudo)

License

GNU Affero General Public License v3.0 - see LICENSE for details.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
tunnelmesh command tunnelmesh is the P2P SSH tunnel mesh network tool.	tunnelmesh is the P2P SSH tunnel mesh network tool.
tunnelmesh-benchmarker command Benchmarker service for Docker - runs aggressive continuous benchmarks between mesh peers.	Benchmarker service for Docker - runs aggressive continuous benchmarks between mesh peers.
tunnelmesh-prometheus-sd-generator command SD Generator for Prometheus file_sd Polls the TunnelMesh coordination server and generates targets file for Prometheus.	SD Generator for Prometheus file_sd Polls the TunnelMesh coordination server and generates targets file for Prometheus.
tunnelmesh-s3bench command tunnelmesh-s3bench is a story-driven S3 stress testing tool.	tunnelmesh-s3bench is a story-driven S3 stress testing tool.
internal
admin
auth
benchmark Package benchmark provides peer-to-peer speed testing over the mesh network.	Package benchmark provides peer-to-peer speed testing over the mesh network.
config Package config handles configuration loading and validation for tunnelmesh.	Package config handles configuration loading and validation for tunnelmesh.
context Package context provides management of multiple TunnelMesh configurations.	Package context provides management of multiple TunnelMesh configurations.
control Package control provides a Unix socket server for CLI-to-daemon communication.	Package control provides a Unix socket server for CLI-to-daemon communication.
coord Package coord provides the TunnelMesh coordinator server.	Package coord provides the TunnelMesh coordinator server.
coord/nfs Package nfs provides an NFS v3 server backed by S3 storage.	Package nfs provides an NFS v3 server backed by S3 storage.
coord/replication
coord/s3 Package s3 provides an S3-compatible object storage service for the coordinator.	Package s3 provides an S3-compatible object storage service for the coordinator.
coord/web
dns Package dns implements a local DNS resolver for the mesh network.	Package dns implements a local DNS resolver for the mesh network.
docker Package docker provides Docker container orchestration for TunnelMesh peers.	Package docker provides Docker container orchestration for TunnelMesh peers.
logging/audit
logging/loki Package loki provides a zerolog writer that pushes logs to Grafana Loki.	Package loki provides a zerolog writer that pushes logs to Grafana Loki.
mesh Package mesh provides constants for the TunnelMesh network configuration.	Package mesh provides constants for the TunnelMesh network configuration.
metrics Package metrics provides Prometheus metrics for tunnelmesh peers.	Package metrics provides Prometheus metrics for tunnelmesh peers.
netmon Package netmon provides network interface change monitoring.	Package netmon provides network interface change monitoring.
peer Package peer provides the core peer functionality for tunnelmesh.	Package peer provides the core peer functionality for tunnelmesh.
peer/connection
portmap Package portmap provides port mapping functionality using PCP, NAT-PMP, and UPnP protocols.	Package portmap provides port mapping functionality using PCP, NAT-PMP, and UPnP protocols.
portmap/client Package client provides protocol implementations for port mapping.	Package client provides protocol implementations for port mapping.
portmap/testutil Package testutil provides test infrastructure for port mapping.	Package testutil provides test infrastructure for port mapping.
promsd Package promsd provides Prometheus service discovery for TunnelMesh peers.	Package promsd provides Prometheus service discovery for TunnelMesh peers.
routing Package routing handles packet routing for the mesh network.	Package routing handles packet routing for the mesh network.
s3bench/documents Package documents provides document generation for story-driven stress testing.	Package documents provides document generation for story-driven stress testing.
s3bench/mesh
s3bench/simulator
s3bench/story Package story defines story-driven stress test scenarios with characters, timelines, and document generation rules.	Package story defines story-driven stress test scenarios with characters, timelines, and document generation rules.
s3bench/story/scenarios Package scenarios contains built-in story scenarios for S3 stress testing.	Package scenarios contains built-in story scenarios for S3 stress testing.
svc Package svc provides cross-platform system service support for TunnelMesh.	Package svc provides cross-platform system service support for TunnelMesh.
tracing Package tracing provides runtime trace recording capabilities using Go 1.25's FlightRecorder.	Package tracing provides runtime trace recording capabilities using Go 1.25's FlightRecorder.
transport Package transport provides a pluggable transport abstraction layer supporting multiple connection types (SSH, UDP, Relay) per peer.	Package transport provides a pluggable transport abstraction layer supporting multiple connection types (SSH, UDP, Relay) per peer.
transport/ssh Package ssh implements the SSH transport for tunnelmesh.	Package ssh implements the SSH transport for tunnelmesh.
transport/udp Package udp implements an encrypted UDP transport for tunnelmesh.	Package udp implements an encrypted UDP transport for tunnelmesh.
tun Package tun provides TUN interface management for tunnelmesh.	Package tun provides TUN interface management for tunnelmesh.
tunnel Package tunnel implements SSH tunnel management for peer-to-peer connections.	Package tunnel implements SSH tunnel management for peer-to-peer connections.
udpenc Package udpenc implements UDP-over-TCP encapsulation for tunnelmesh.	Package udpenc implements UDP-over-TCP encapsulation for tunnelmesh.
update Package update provides self-update functionality for the tunnelmesh CLI.	Package update provides self-update functionality for the tunnelmesh CLI.
pkg
bytesize Package bytesize provides utilities for parsing and formatting byte sizes.	Package bytesize provides utilities for parsing and formatting byte sizes.
proto Package proto defines shared protocol messages for tunnelmesh.	Package proto defines shared protocol messages for tunnelmesh.
testutil Package testutil provides shared test utilities and mocks for tunnelmesh tests.	Package testutil provides shared test utilities and mocks for tunnelmesh tests.