Shulker vMesh v3.1.0
Zero-overhead, multi-region GRE mesh network. Connect VPSes, VDSes, and Bare Metal machines via private IPs across different datacenters — with almost zero overhead.
What is vMesh?
🔗 vMesh enables private network between any Shulker infrastructure — VPS, VDS, Bare Metal — regardless of physical location. Your servers communicate using private IPs as if they were in the same rack.
Architecture Overview
┌─────────────────────────────────────────────────────────────────────────────────────┐ │ Shulker vMesh Control Plane │ │ API: https://shulker.in/api/vmesh-v1 │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ vMesh Node │ │ vMesh Node │ │ vMesh Node │ │ │ │ (Frankfurt) │ │ (Mumbai) │ │ (Virginia) │ │ │ │ │ │ │ │ │ │ │ │ Public: 1.2.3.4│ │ Public:5.6.7.8 │ │ Public:9.10.11.12│ │ │ │ Private:10.99.1.1│ │ Private:10.99.1.2│ │ Private:10.99.1.3│ │ │ │ │ │ │ │ │ │ │ │ ┌───────────┐ │ │ ┌───────────┐ │ │ ┌───────────┐ │ │ │ │ │ GRE ├──┼────┼──► GRE ├──┼────┼──► GRE │ │ │ │ │ │ Tunnel │◄─┼────┼──┤ Tunnel │◄─┼────┼──┤ Tunnel │ │ │ │ │ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │ │ │ │ ▲ │ │ ▲ │ │ ▲ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌─────┴─────┐ │ │ ┌─────┴─────┐ │ │ ┌─────┴─────┐ │ │ │ │ │ VPS Apps │ │ │ │ Database │ │ │ │ Storage │ │ │ │ │ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ Private Mesh Subnet: 10.99.1.0/24 │ GRE Protocol 47 │ Auto-Healing Tunnels │ └─────────────────────────────────────────────────────────────────────────────────────┘
Each node establishes direct GRE tunnels to all other nodes — creating a true mesh network
Quick Install
Run this command on each server you want to add to the vMesh network.
bash <(curl -s https://shulker.in/cdn/vmesh/setup.sh) -token YOUR_VMESH_TOKEN
vmesh status to check tunnel health.✅ What the installer does — Removes any previous installation, installs dependencies (iproute2, jq, curl, iptables), fetches config from API, writes systemd services (core daemon, config watcher, monitor), and starts everything. Changes apply automatically within 5 seconds.
How vMesh Works
vMesh creates a full-mesh GRE tunnel network between all your nodes, with API-driven configuration and real-time monitoring.
┌─────────────────────────────────────────────────────────────────────────────┐ │ vMesh Component Architecture │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────┐ ┌─────────────────────────────────────┐ │ │ │ vMesh Dashboard API │ │ Node: Frankfurt │ │ │ │ (shulker.in/api/vmesh) │ │ │ │ │ └───────────┬─────────────┘ │ ┌───────────┐ ┌───────────┐ │ │ │ │ │ │ Watcher │ │ Monitor │ │ │ │ │ ┌───────────────┼──►│ (polls 5s)│ │(pushes 15s)│ │ │ │ │ │ │ └─────┬─────┘ └─────┬─────┘ │ │ │ ▼ ▼ │ │ │ │ │ │ ┌─────────────────────────┐ │ ▼ ▼ │ │ │ │ Central Config Store │ │ ┌─────────────────────────────┐ │ │ │ │ (JSON + ACL + Hash) │ │ │ Core Daemon │ │ │ │ └─────────────────────────┘ │ │ - Creates GRE tunnels │ │ │ │ │ │ - Applies ACL rules │ │ │ │ │ │ - Handles keepalive │ │ │ │ │ │ - Auto-heals down tunnels │ │ │ │ │ └─────────────────────────────┘ │ │ │ │ │ │ │ │ ┌─────────────────────────────┐ │ │ │ │ │ Mesh Subnet │ │ │ │ │ │ 10.99.1.0/24 │ │ │ │ │ └─────────────────────────────┘ │ │ │ └─────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘
Prerequisites
| Requirement | Details |
|---|---|
| Root Access | vMesh requires root/sudo privileges to create GRE tunnels and iptables rules. |
| GRE Protocol | Ensure your provider allows GRE (IP protocol 47). All Shulker infrastructure supports this. |
| Public IP | Each node needs a public IP for tunnel endpoints. |
| Linux Kernel | vMesh works on any modern Linux distribution (Ubuntu 18.04+, Debian 10+, CentOS 7+). |
| API Access | Nodes must be able to reach shulker.in (port 443). |
CLI Reference
The vmesh command provides full control over your mesh network.
vmesh status
═══════════════════════════════════════════════════════════════════════
✅ shulker-vmesh active
✅ vmesh-watcher active
✅ vmesh-monitor active
════════════════════ Active GRE Tunnels ════════════════════
gre1x2 UP
addr: 10.99.1.2/32 peer 10.99.1.1/32 dev gre1x2
route: 10.99.1.1 dev gre1x2 proto static scope link
gre1x3 UP
addr: 10.99.1.3/32 peer 10.99.1.1/32 dev gre1x3
route: 10.99.1.3 dev gre1x3 proto static scope link
════════════════════ Peer States ═══════════════════════════
frankfurt UP (2025-01-15 10:30:45)
virginia UP (2025-01-15 10:30:47)
Config hash: a3f5e9d1c8b2a4e6f7g8h9i0j1k2l3m4
vMesh Dashboard
Manage your entire mesh network from the Shulker dashboard at /panel/dashboard/vmesh.
Configuration Files
{
"network": {
"subnet": "10.99.1.0/24",
"gre_key_base": 100,
"mtu": 1476,
"keepalive_sec": 15
},
"transit": {
"enabled": false,
"forward_to_peer": "",
"inbound_interface": "AUTO"
},
"this_node": {
"name": "frankfurt-node",
"public_ip": "1.2.3.4",
"private_ip": "10.99.1.1"
},
"peers": [
{
"name": "mumbai-node",
"public_ip": "5.6.7.8",
"private_ip": "10.99.1.2"
},
{
"name": "virginia-node",
"public_ip": "9.10.11.12",
"private_ip": "10.99.1.3"
}
]
}
{
"default_policy": "deny",
"rules": [
{
"src": "10.99.1.1",
"dst": "10.99.1.2",
"proto": "tcp",
"port": "5432",
"action": "allow",
"comment": "PostgreSQL access from Frankfurt to Mumbai"
},
{
"src": "any",
"dst": "10.99.1.0/24",
"proto": "icmp",
"action": "allow",
"comment": "Allow ping within mesh"
}
]
}
Troubleshooting
❌ Tunnel won't come up — Check that GRE protocol (IP 47) is allowed. Verify both endpoints have public IPs and can reach each other. Run vmesh logs to see detailed error messages.
🔐 Permission errors — The installer must run as root. Use sudo if not already root. Check that /etc/shulker-vmesh directory permissions are correct (700).
🔄 Config not updating — The watcher polls every 5 seconds. Check vmesh wlogs to see if API calls are succeeding. Verify your token is valid and the dashboard config is published.
📊 Stats not appearing in dashboard — Ensure the monitor daemon is running: systemctl status vmesh-monitor. Check vmesh mlogs for API push errors. Verify the node name in config matches the dashboard.
Best Practices
🔒 Start with a restrictive ACL — Set default_policy: "deny" and explicitly allow only necessary traffic between specific nodes. This follows the principle of least privilege.
📊 Monitor tunnel health — Use vmesh status regularly. Set up external monitoring to alert on peer state changes.
🌐 Use consistent private IPs — Assign predictable private IPs across your mesh (e.g., 10.99.1.x where x matches your node ID). Document your IP assignment scheme.
⚠️ Transit routing caution — Transit mode routes public traffic through the mesh — ensure you understand the implications before enabling.
Quick Reference
# Install vMesh on a node bash <(curl -s https://shulker.in/cdn/vmesh/setup.sh) -token YOUR_TOKEN # Check full status vmesh status # View live logs vmesh logs # Core daemon vmesh wlogs # Config watcher vmesh mlogs # Monitor daemon # Reload config without restart (hot-reload) vmesh reload # List active GRE tunnels vmesh peers # Validate configuration files vmesh verify # Edit config vmesh config vmesh rules