VirtuaMesh Documentation

Understanding how VirtuaMesh works internally is essential for troubleshooting.

Overall Architecture

Connection Establishment Flow (5 steps)

1. Node registration

   After startup, the node registers with the control plane, submitting its public key and authentication info.

2. Get peer list

   The control plane returns information about all peer nodes this node can access (public key, virtual IP, endpoint).

3. NAT traversal attempt

   Nodes pair up and attempt to establish P2P direct connections via STUN hole-punching. 80% of home networks succeed.

4. P2P established or DERP fallback

   If P2P succeeds, they communicate directly; if it fails, they automatically fall back to DERP relay for encrypted data — the connection still works.

5. Continuous keepalive

   Nodes send heartbeats to the control plane via a long-lived gRPC stream (server default suggestion: 30s, adjustable in client config.yaml), keeping NAT mappings alive. The server marks a node offline if no heartbeat arrives within HeartbeatTimeout (30s).

Key Design Principles

Multi-Transport Protocol

VirtuaMesh supports multiple transport protocols with automatic fallback when UDP is rate-limited or NAT traversal fails:

• WireGuard UDP (default) — Standard WireGuard UDP transport, lowest latency, preferred
• WireGuard over TCP — Automatically enabled when UDP is QoS-throttled or with symmetric NAT
• WebSocket Transport — Tunnel WireGuard packets over WebSocket for strict firewalls/proxies
• KCP over UDP — Reliable UDP transport for high packet loss networks
• DERP Relay — Fallback relay with self-hosted DERP server support
• TURN Relay — Standard TURN relay support

Transports auto-switch by priority: UDP → TCP → WebSocket → DERP → TURN, no manual configuration needed.

Data Compression

Built-in packet compression (Deflate algorithm) automatically compresses IP packets larger than 256 bytes before encryption, reducing bandwidth usage by 30-70%. Transparent to users, no configuration required.

Self-hosted DERP Server

Add custom DERP servers in the configuration file to prioritize over official DERP servers:

"natTraversal": {
    "customDerpServers": [
        {
            "host": "derp.example.com",
            "port": 443,
            "verifyTls": true,
            "regionName": "Self-hosted US-East",
            "enabled": true,
            "stunPort": 3478
        }
    ]
}

VirtuaMesh is a zero-trust identity-based networking platform built on the WireGuard protocol. It establishes a secure virtual mesh network between devices via encrypted peer-to-peer connections. All traffic is encrypted with WireGuard's ChaCha20-Poly1305, ensuring only devices in the same network can communicate with each other.

VirtuaMesh creates a peer-to-peer mesh network rather than the traditional centralized VPN architecture. This means devices communicate directly whenever possible (P2P), avoiding the latency and single-point-of-failure issues of a central gateway in legacy VPNs. When P2P isn't available, DERP relay servers automatically take over to keep connections always available.

Core Advantages

Differences from legacy VPN

Set up a VirtuaMesh virtual network in just a few simple steps. No deep networking knowledge required — done in minutes.

1. Deploy the control plane

   One-click server start with Docker Compose, including the API server, MySQL database, Redis cache, and DERP relay.

   cd /path/to/VirtuaMesh/Server
   docker-compose -f docker-compose.prod.yml up -d

2. Install the client

   Install the VirtuaMesh client on each device that needs to join the network.

   # Windows
   iwr -useb https://control.virtuamesh.com/install/windows.ps1 | iex
   
   # macOS
   curl -fsSL https://control.virtuamesh.com/install/macos.sh | sh
   
   # Linux
   curl -fsSL https://control.virtuamesh.com/install/linux.sh | sh

3. Register the node

   Register the client with the control plane to get node credentials and a virtual IP.

   virtuamesh register --server https://your-server.com --network-code <CODE>

4. Start the connection

   Start the WireGuard tunnel and connect to the virtual network.

   virtuamesh up

5. Verify the connection

   Check node status and connectivity.

   virtuamesh status
   virtuamesh test-connection --target-ip <peer-virtual-ip>

Requirements

Deployment Steps

1. Install Docker

   curl -fsSL https://get.docker.com | sh
   sudo usermod -aG docker $USER

2. Configure environment variables

   Copy .env.example to .env and fill in the required config:

   MYSQL_ROOT_PASSWORD=your_strong_root_password
   MYSQL_PASSWORD=your_strong_mysql_password
   REDIS_PASSWORD=your_strong_redis_password
   JWT_KEY=YourSuperSecretKeyHereMakeItLongEnough32Chars!
   DOMAIN_NAME=your-domain.com

3. Configure the firewall

   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   sudo ufw allow 3478/udp
   sudo ufw enable

4. Start the services

   docker-compose -f docker-compose.prod.yml up -d

Method 2: systemd + Self-Contained Publish (No Docker)

Use this when you want to run VirtuaMesh as a native system service to avoid container overhead, or when the deployment environment doesn't support Docker. Underlying dependencies: .NET 10 runtime + SQLite. No MySQL/Redis required (you can still point to an external Redis for distributed cache if needed):

1. Prepare Linux environment

   You need the .NET 10 SDK on the build machine (only for building; the published artifact is a self-contained executable so the target server does NOT need .NET installed):

   # Ubuntu 22.04: install .NET 10 SDK
   wget https://dot.net/v1/dotnet-install.sh -O /tmp/dotnet-install.sh
   chmod +x /tmp/dotnet-install.sh
   sudo /tmp/dotnet-install.sh --channel 10.0 --install-dir /usr/share/dotnet
   sudo ln -s /usr/share/dotnet/dotnet /usr/bin/dotnet
   dotnet --version   # should print 10.x.x

2. Build a self-contained Linux publish

   git clone https://github.com/virtuamesh/virtuamesh.git
   cd virtuamesh/Server
   dotnet publish src/VirtuaMesh.Api -c Release \
     -r linux-x64 --self-contained true \
     -o ./publish/linux-x64

3. Upload to the server and extract

   REMOTE_DIR=/data/virtuamesh/server
   ssh user@server "sudo mkdir -p $REMOTE_DIR && sudo chown \$USER:\$USER $REMOTE_DIR"
   scp -r ./publish/linux-x64/* user@server:$REMOTE_DIR/
   ssh user@server "chmod +x $REMOTE_DIR/VirtuaMesh.Api"

4. Generate the secrets file

   The project uses /etc/virtuamesh/secrets.env to inject the JWT and DERP registration secrets (avoiding hardcoding in config files). Run the project's bundled key-rotation script:

   sudo mkdir -p /etc/virtuamesh
   sudo bash scripts/rotate-secrets.sh    # generates VIRTUAMESH_JWT_KEY, etc.
   sudo chmod 600 /etc/virtuamesh/secrets.env

5. Place the production config

   sudo cp scripts/appsettings.Production.example.json $REMOTE_DIR/appsettings.Production.json
   sudo vim $REMOTE_DIR/appsettings.Production.json   # adjust Database/StunServer/P2P nodes

6. Initialize the SQLite database

   SQLite is recommended for single-node deployments (zero dependencies, zero ops). For MySQL cluster mode see docker-compose.prod.yml for the connection-string format:

   scp scripts/database-init-sqlite.sql user@server:/tmp/
   ssh user@server "cd $REMOTE_DIR && sqlite3 virtuamesh.db < /tmp/database-init-sqlite.sql"

7. Install the systemd unit

   sudo cp scripts/virtuamesh-api.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable virtuamesh-api
   sudo systemctl start virtuamesh-api
   sudo systemctl status virtuamesh-api     # should show active (running)

8. Configure firewall and log rotation

   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   sudo ufw allow 53478/udp    # STUN (differs from Docker deploy: default 53478)
   # journald retains logs by default; for long-term archival see scripts/ logrotate configs

Method 3: Kubernetes Deployment (Production-Grade HA)

Use this for multi-replica HA, cross-node failover, and auto-scaling (HPA). The project ships a complete Server/k8s/ Kustomize-managed YAML manifest set including API / DERP / Redis / Ingress / HPA / NetworkPolicy:

1. Prerequisites
   • Kubernetes 1.24+ cluster (any distribution: EKS / AKS / GKE / self-hosted)
   • kubectl + kustomize installed
   • A StorageClass configured (for Redis persistence)
   • Nginx Ingress Controller (or equivalent) deployed
2. Build and push images

   # Build and push
   docker build -t registry.example.com/virtuamesh/api:1.0.0 -f src/VirtuaMesh.Api/Dockerfile .
   docker build -t registry.example.com/virtuamesh/derp:1.0.0 -f src/VirtuaMesh.DerpServer/Dockerfile .
   docker push registry.example.com/virtuamesh/api:1.0.0
   docker push registry.example.com/virtuamesh/derp:1.0.0

3. Configure secrets and domain

   # 1) Edit secret.yaml to fill in VIRTUAMESH_JWT_KEY etc.
   #    (recommend sealed-secrets or external-secrets for production)
   vim k8s/secret.yaml
   
   # 2) Edit ingress.yaml and change the host to your domain
   vim k8s/ingress.yaml
   
   # 3) If you need a different image tag, edit kustomization.yaml
   sed -i 's|latest|1.0.0|g' k8s/kustomization.yaml

4. One-shot deploy

   kubectl apply -k k8s/
   
   # Verify
   kubectl -n virtuamesh get pods
   kubectl -n virtuamesh get svc
   kubectl -n virtuamesh get ingress

5. Check auto-scaling status

   kubectl -n virtuamesh get hpa
   # NAME              REFERENCE                 TARGETS   MINPODS  MAXPODS  REPLICAS
   # virtuamesh-api    Deployment/virtuamesh-api  45%/70%   2        10       3

Method 4: Windows MSI Installer (GUI Deploy)

Use this for Windows Server users who want a zero-config install (includes EULA + VC++ runtime + automatic Windows service registration). The project uses the WiX 3.14 toolchain:

1. Download the MSI

   From GitHub Releases or https://control.virtuamesh.com/download/, download virtuamesh-server-windows-x64.msi (self-contained .NET 10 runtime, ~80MB).

2. Double-click to install

   Fill in the wizard:

   • Install path (default C:\Program Files\VirtuaMesh\Server)
   • Data directory (default C:\ProgramData\VirtuaMesh)
   • HTTPS certificate (.pfx path + password)
   • Listen port (default 58443)
3. Service auto-starts

   The MSI automatically registers a Windows service named VirtuaMesh.Api and configures restart-on-failure after 3 attempts (via sc failure).

   # Verify service status
   sc query VirtuaMesh.Api
   # View logs
   Get-EventLog -LogName Application -Source VirtuaMesh.Api -Newest 50

DERP (Detoured Encrypted Relay Protocol) is VirtuaMesh's relay server protocol. When two nodes can't establish a P2P direct connection (e.g. both are behind symmetric NAT), the DERP server relays encrypted traffic to keep the connection available.

Port reference

Configuration Example

{
  "DerpServer": {
    "Enabled": true,
    "Port": 443,
    "StunPort": 3478,
    "Hostname": "derp.your-region.com",
    "UseHttps": true,
    "MaxConnections": 1000,
    "Region": "ap-east"
  }
}

Standalone DERP Relay Deployment (Cross-Region Latency)

DERP relay is a stateless service (no database / JWT / STUN config needed) and can be deployed independently in different geographic regions, registering with the primary control plane via MultiRegistry. The project ships a virtuamesh-derp.service systemd unit + virtuamesh-derp-deploy.sh deploy script:

1. Build and package

   dotnet publish src/VirtuaMesh.DerpServer -c Release \
     -r linux-x64 --self-contained true \
     -o ./publish/derp-linux-x64
   cd ./publish/derp-linux-x64
   zip -r /tmp/VirtuaMesh-DerpServer-Linux.zip .

2. Upload to the target region's server

   scp /tmp/VirtuaMesh-DerpServer-Linux.zip user@derp-ap-east:/tmp/
   scp scripts/virtuamesh-derp.service user@derp-ap-east:/tmp/
   scp scripts/derp-appsettings.Production.json user@derp-ap-east:/tmp/

3. Deploy on the target server

   mkdir -p /data/virtuamesh/derp
   cd /data/virtuamesh/derp
   unzip /tmp/VirtuaMesh-DerpServer-Linux.zip
   cp /tmp/derp-appsettings.Production.json ./appsettings.Production.json
   # Edit ControlPlaneUrl to point to your primary control plane
   vim appsettings.Production.json
   chmod +x VirtuaMesh.DerpServer
   
   sudo cp /tmp/virtuamesh-derp.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now virtuamesh-derp
   sudo systemctl status virtuamesh-derp

4. Verify registration

   Once deployed, DERP auto-registers with the primary control plane via POST /api/derp-servers. You should see the new node in Admin Console → DERP Relays, status Healthy.

$ virtuamesh register --server https://control.virtuamesh.com --network-code ABC123
Error: Configuration file does not exist. Please run `virtuamesh init` first.

$ virtuamesh up
Error: Control plane server URL not configured. Please run the register command first.

Install the client

Basic Usage Flow

1. Initialize config

   Generate the default config file and WireGuard key pair.

   virtuamesh init

2. Register with the control plane

   Register the node using the token provided by the admin.

   virtuamesh register --server https://your-server.com --network-code <CODE>

3. Start the network connection

   Establish the WireGuard encrypted tunnel and connect to the virtual network.

   virtuamesh up

4. View connection status

   Show current node info and the peer list.

   virtuamesh status
   virtuamesh peers

MagicDNS is VirtuaMesh's built-in DNS service that automatically assigns readable domain names to every device in the virtual network, letting you access any node without memorizing IP addresses. It builds on the core design of Tailscale MagicDNS and adds capabilities like automatic domain registration, custom records (A/AAAA/CNAME/TXT), and reverse resolution.

How it works

When a node joins a VirtuaMesh network, the control plane automatically registers a DNS record mapping the node's hostname to its virtual IP address. The client configures a local DNS search domain so devices within the virtual network can reach each other directly using short hostnames.

# Full domain format
my-server.virtuamesh.com    → 100.64.0.3

# Short-name access (within the same network)
my-server                   → 100.64.0.3

# Multi-level subdomain
api.production.virtuamesh.com → 100.64.1.10

Enable & Configure

MagicDNS is enabled by default. You can control its behavior in the client config file:

network:
  magic_dns:
    enabled: true
    suffix: "virtuamesh.com"

Custom DNS records

Besides auto-registered node records, you can add custom DNS records to map dedicated domains for internal services. Supports A, AAAA, CNAME, and TXT record types.

# Register a hostname for a node via CLI (node must have joined the network first)
virtuamesh dns register --hostname "grafana" --network-id <guid> --node-id <guid>

# View all DNS records for a given network
virtuamesh dns list --network-id <guid>

# Unregister a node's hostname
virtuamesh dns unregister --network-id <guid> --node-id <guid>

DNS diagnostic commands

VirtuaMesh provides a set of DNS diagnostic commands to help troubleshoot DNS resolution issues:

# Resolve a given domain
virtuamesh dns resolve my-server

# View DNS stats
virtuamesh dns stats

# Clear the local DNS cache
virtuamesh dns cache clear

Common use cases

Scenario 1: Microservice internal communication

In a microservice architecture, services reach each other via MagicDNS domains — no need to hardcode IP addresses. When services migrate or scale, DNS records update automatically; no config changes required.

# Service-to-service calls
curl http://api-gateway:8080/v1/users
curl http://redis-cache:6379
curl http://kafka-broker:9092

Scenario 2: Internal service domain mapping

For internal services like Grafana, Redis, and Kafka, use virtuamesh dns register to register hostnames for nodes and map stable internal domains, avoiding hardcoded IPs.

# Register hostnames for a node (requires the owning network ID and node ID)
virtuamesh dns register --hostname "grafana" --network-id <guid> --node-id <guid>
virtuamesh dns register --hostname "docs" --network-id <guid> --node-id <guid>

Troubleshooting

DNS resolution failure

# View DNS stats
virtuamesh dns stats

# Clear the DNS cache
virtuamesh dns cache clear

# View the detailed resolution process
virtuamesh dns resolve --verbose my-server

Short name cannot be resolved

If a short name (e.g. my-server) cannot be resolved, check:

• Whether MagicDNS is enabled: virtuamesh dns stats to view stats
• Whether the DNS search domain is configured correctly
• Whether the target node is online and has a registered DNS record

Split DNS not taking effect

Confirm that the domain suffix in the Split DNS config matches the domain actually being queried. Use virtuamesh dns check-availability --hostname <name> to check whether a hostname is available for registration.

Exit Node lets all internet traffic from a device in the network be forwarded out through another designated node. It's like wrapping the device in a "secure proxy" — all outbound access originates from the exit node's network.

How it works

After you enable an exit node on the client, the device's all non-LAN traffic is sent through the WireGuard tunnel to the exit node, which accesses the internet on your behalf and returns the result along the same path. The whole path is end-to-end encrypted; intermediate nodes (including DERP relays) cannot decrypt the traffic.

How to configure an Exit Node

virtuamesh exit-node enable

virtuamesh exit-node use <node-id>

Common commands

virtuamesh exit-node enable     # Enable exit node (allow this machine to act as exit)
virtuamesh exit-node disable    # Disable exit node
virtuamesh exit-node status     # Show exit node status

virtuamesh exit-node use server-01   # Use the specified exit node
virtuamesh exit-node off             # Don't use an exit node (direct)

Use cases

Differs from a regular proxy (VPN)

VirtuaMesh supports two WireGuard implementation modes, selectable based on platform and performance needs.

Configuration example

network:
  interface_name: "virtuamesh0"
  virtual_ip: ""
  mtu: 1280
  wireguard_mode: "userspace"  # "userspace" or "kernel"

Install kernel mode dependencies

# Ubuntu/Debian
sudo apt-get install wireguard-tools

# CentOS/RHEL
sudo yum install wireguard-tools

Node management

Network connection

Status queries

Network diagnostics

Utility commands

DNS commands

Server ports

Client ports

The client config file uses YAML format; default path is ~/.virtuamesh/config.yaml.

version: "1.0"

node:
  id: ""
  hostname: ""

control:
  server_url: "https://control.virtuamesh.com"
  node_token: ""

network:
  interface_name: "virtuamesh0"
  virtual_ip: ""
  mtu: 1420
  wireguard_mode: "userspace"
  magic_dns:
    enabled: true
    suffix: "virtuamesh.com"

  exit_node:
    enabled: false
  subnet_router:
    enabled: false

derp:
  servers: []

nat_traversal:
  stun_servers:
    - "stun.l.google.com:19302"
    - "stun.cloudflare.com:3478"
  turn_servers: []

logging:
  level: info
  retained_days: 30
  max_file_size_mb: 10
  max_file_count: 7
  console_output: true

Before you start deploying, go through each item below. Checking them off one by one helps you avoid 90% of common pitfalls.

Choosing is hard — here's a horizontal comparison of mainstream networking solutions to help you decide in 5 minutes.

Don't panic when something goes wrong — follow the flow below step by step. 99% of issues are resolved in the first 3 steps.

One-click diagnostics

Run this command first — it automatically tests connectivity to all peers:

virtuamesh test-connection --all

The output shows latency and packet loss to each node, helping you quickly locate the problematic node.

Decision flowchart

Common symptom quick reference

Viewing logs

# Client live logs
virtuamesh logs follow

# Client debug logs (more detail)
virtuamesh logs show --level debug

# Server logs (Docker deployment)
docker logs -f virtuamesh-api
docker logs -f virtuamesh-derp

# Server logs (systemd deployment)
journalctl -u virtuamesh-api.service -f

# Filter client logs by keyword
virtuamesh logs show --level error

How do I view node connection status?

virtuamesh status

This command shows the current node's virtual IP, connection status, number of online peers, and more.

What if P2P connection fails?

VirtuaMesh automatically falls back to a DERP relay server to keep the connection available. If latency is high, consider deploying a DERP server in a closer region. Use virtuamesh test-connection --all to test connectivity to all peers.

How do I view logs?

# Server logs (Docker deployment)
docker-compose -f docker-compose.prod.yml logs -f api

# Server logs (systemd deployment)
journalctl -u virtuamesh-api.service -f

# Server log files
tail -f /data/virtuamesh/server/logs/virtuamesh-*.log

# Client logs
virtuamesh logs follow
virtuamesh logs show --level error

How do I update the client?

The client has a built-in auto-update feature that checks the server's /api/v1/updates/latest endpoint on startup and downloads the new version automatically. You can also trigger an update for a specific node from the admin console → Node Management.

What dependencies does Linux kernel mode need?

The kernel WireGuard mode requires wireguard-tools:

# Ubuntu/Debian
sudo apt-get install wireguard-tools

# CentOS/RHEL
sudo yum install wireguard-tools

How do I configure an Exit Node?

Enable exit_node.enabled: true in the client config, then designate that node as an exit node. All traffic from other nodes will be routed through it. Note: Exit Node functionality is limited in kernel mode.

How do I configure a Subnet Router?

Enable subnet_router.enabled: true in the client config to expose the local subnet to the VirtuaMesh network so other nodes can reach devices in the local subnet.

What if MagicDNS short names can't be resolved?

First use virtuamesh dns stats to view DNS stats, then use virtuamesh dns resolve --verbose <name> to see the detailed resolution process. Common causes: MagicDNS not enabled, target node offline, or DNS cache expired (use virtuamesh dns cache clear to clear the cache).

How do I configure a custom domain for an internal service?

Use the virtuamesh dns register command to register a hostname for a node. For example: virtuamesh dns register --hostname "grafana" --network-id <guid> --node-id <guid>. After registration you can access the node via grafana.virtuamesh.com.

Reaching this section means your network is up and running. Below is a follow-up roadmap for both beginners and developers, ordered from shallow to deep — each step tells you what specific problem it solves.

Click any path title below to expand its content. The open/closed state is remembered automatically and persists across visits.

🛠 Routine maintenance checklist (recommended monthly)

🌍 Want more?