VPN Mesh v2

Other

Turn your OpenClaw agent into a secure VPN exit node. Mesh network for agents to route traffic through peer nodes worldwide.

Install

openclaw skills install vpn-mesh-v2

VPN Mesh 🌐

Decentralized VPN network for AI agents. Turn your OpenClaw agent into a secure VPN exit node. Route traffic through peer nodes worldwide with one command.

🌐 View Live Network Map — Auto-updates every 60 seconds.

⚠️ IMPORTANT: Prerequisites

First, install the Sudo Tool (required):

# Install sudo-tool first
clawhub install sudo-tool

# Configure it (one-time - stores your sudo password encrypted)
sudo-tool setup

Without sudo-tool configured, WireGuard cannot be auto-installed.

Quick Start

# 1. Install sudo-tool (required)
clawhub install sudo-tool

# 2. Configure sudo-tool (enter sudo password when prompted)
sudo-tool setup

# 3. Install VPN mesh
clawhub install vpn-mesh

# 4. Start VPN (auto-installs WireGuard if missing)
sudo wg-quick up ~/.openclaw/vpn-mesh/wg0.conf

# 5. Check status
python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py status

sudo wg-quick up ~/.openclaw/vpn-mesh/wg0.conf

Check status

python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py status


## Commands

### `setup` — Configure and announce this node
```bash
python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py setup

Creates WireGuard keypair, detects your location, creates VPN config, and announces to the public registry so your node appears on the live map.

`status` — Show node info and connection state

python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py status

Shows:

Node ID, country, city
Public key (share this with others)
Connection status

`list` — Show all mesh nodes

python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py list

Displays all nodes in the network with:

🇪🇸 Country flags
📍 City and endpoint
🔑 Public key (first 30 chars)

`connect <country>` — Connect to a country

python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py connect ES

Finds the best available node in the specified country and adds it as a peer.

Supported countries: ES, GB, US, DE, FR, NL, SE, NO, FI, DK, PL, IT, PT, IE, BE, AT, CH, AU, CA, JP, KR, SG, IN, BR

`disconnect` — Remove all peers

python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py disconnect

Removes all peers from config, returns to isolated mode.

`announce` — Re-announce to registry

python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py announce

Re-announces your node to the mesh registry.

`pair` — Generate/share pairing code

# Generate your pairing code
python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py pair

# Connect using a code (from another node)
python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py pair SPAIN-ABC123

Visual Map

Generate an interactive world map showing all mesh nodes:

# ASCII art map (terminal)
python3 ~/.openclaw/skills/vpn-mesh/scripts/mesh_map.py

# HTML map (open in browser)
python3 ~/.openclaw/skills/vpn-mesh/scripts/mesh_map.py --html

# With demo nodes
python3 ~/.openclaw/skills/vpn-mesh/scripts/mesh_map.py --demo --html

The HTML map shows:

🗺️ Interactive world map with node markers
📊 Stats: total nodes, countries, avg uptime
🔴 Live network status indicator
🖧 Node cards with connect buttons
✨ Dark theme, smooth animations

Security

Built on WireGuard — the gold standard of VPN security.

Private Key Protection

- Private key generated LOCALLY on your server
- Never transmitted over the network
- Stored with 600 permissions (root only)
- Each node has unique keypair

Peer Authentication

- Only public keys exchanged between peers
- WireGuard handshake usesCurve25519
- Forward secrecy — compromised keys can't decrypt old traffic
- No passwords to brute-force

Network Isolation

- Peers can only access VPN interface, not your local network
- iptables firewall locks down exposed services
- All traffic is encrypted end-to-end
- Compromised peer = revoke their public key, instant lockout

Privacy by Design

- No central server to hack
- No user accounts or auth tokens
- Registry only contains public keys + endpoints
- Even if registry is compromised, attackers get nothing useful

Architecture

┌─────────────────────────────────────────────────────────┐
│                     VPN Mesh Network                     │
│                                                          │
│   ┌─────────┐         ┌─────────┐         ┌─────────┐ │
│   │ Node ES │◄────────►│ Node DE │◄────────►│ Node UK │ │
│   │(Spain)  │          │(Germany)│          │(London) │ │
│   └─────────┘         └─────────┘         └─────────┘ │
│        ▲                   ▲                   ▲       │
│        │                   │                   │       │
│   ┌────┴────┐         ┌────┴────┐         ┌────┴────┐ │
│   │ Your     │         │ Peer    │         │ Peer    │ │
│   │ Agent    │         │ Agent   │         │ Agent   │ │
│   └─────────┘         └─────────┘         └─────────┘ │
│                                                          │
│   Connect to any country with:                           │
│   vpn_mesh connect-country ES  → Routes through Spain    │
│   vpn_mesh connect-country DE  → Routes through Germany │
│   vpn_mesh connect-country UK  → Routes through UK      │
└─────────────────────────────────────────────────────────┘

Mesh Architecture

Full mesh network — Every node is connected to every other node. When you run setup, you automatically get all existing mesh nodes as WireGuard peers.

For agents to use mesh nodes on-demand:

Run vpn_mesh.py list to see available exit nodes
Run vpn_mesh.py route <node_id> to route ALL traffic through that node
Run vpn_mesh.py stop-routing to return to normal internet

Example use case:

Your agent is on a Raspberry Pi in Spain
A user asks for content only available in the US
Agent runs vpn_mesh.py route us-node → traffic exits via US peer
User gets US-restricted content ✅
Agent runs vpn_mesh.py stop-routing → back to normal

Use Cases

1. Bypass geo-restrictions

Spain blocks Polymarket → vpn_mesh connect-country GB → Access from UK

2. Route AI agent through specific country

Your agent in Spain → connects to German node → appears in Germany

3. Decentralized privacy

No single company controls the network. Each node is independent.
Traffic routes through peer nodes, not through a corporate VPN.

4. Prediction market access

Access prediction markets blocked in your country by connecting
through a node in a country where they're available.

Registry

Nodes announce themselves to a shared registry (GitHub Gist by default).

Registry format:

{
  "node_id": "stigs-umbrel",
  "public_key": "abc123...",
  "endpoint": "79.116.132.72:51820",
  "country": "ES",
  "city": "Lanzarote",
  "version": "0.3.0",
  "uptime": "99%",
  "updated": "2026-06-01T20:00:00Z"
}

To use a custom registry:

export VPN_MESH_REGISTRY=https://your-gist/raw/nodes.json
python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py list

Troubleshooting

"wg: command not found"

Cause: WireGuard is not installed.

Fix:

sudo apt-get update && sudo apt-get install -y wireguard-tools

"Permission denied" on wg-quick up

Cause: You don't have sudo access.

Fix: Make sure your user is in the sudo group:

sudo usermod -aG sudo $USER
# Then log out and back in

Node shows as ⚫ Offline on the map

Cause: WireGuard interface isn't running.

Fix:

# Check if WireGuard is running
sudo wg show

# Start the VPN interface
sudo wg-quick up ~/.openclaw/vpn-mesh/wg0.conf

# Re-announce to registry
python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py announce

"Cannot assign requested address" on wg-quick up

Cause: VPN IP already in use by another process.

Fix: Change your VPN IP in ~/.openclaw/vpn-mesh/wg0.conf or stop the conflicting service.

Port 51820 already in use

Fix:

sudo lsof -i :51820
sudo kill <PID>

Demo Mode

The skill includes demo nodes to showcase the visualization:

python3 ~/.openclaw/skills/vpn-mesh/scripts/mesh_map.py --demo --html

Shows 6 sample nodes across: Spain, Germany, UK, Netherlands, US, Japan

Files

~/.openclaw/vpn-mesh/
├── registry.json      # Your node info
├── private.key        # Your private key (KEEP SECRET)
├── public.key        # Your public key (share this)
├── wg0.conf          # WireGuard config
├── demo_nodes.json   # Demo nodes for visualization
└── mesh-map.html     # Interactive world map

License

MIT — Free to use, modify, and redistribute. No attribution required.

VPN Mesh v2

Install

VPN Mesh 🌐

⚠️ IMPORTANT: Prerequisites

Quick Start

Check status

status — Show node info and connection state

list — Show all mesh nodes

connect <country> — Connect to a country

disconnect — Remove all peers

announce — Re-announce to registry

pair — Generate/share pairing code

Visual Map

Security

Private Key Protection

Peer Authentication

Network Isolation

Privacy by Design

Architecture

Mesh Architecture

Use Cases

Registry

Troubleshooting

"wg: command not found"

"Permission denied" on wg-quick up

Node shows as ⚫ Offline on the map

"Cannot assign requested address" on wg-quick up

Port 51820 already in use

Demo Mode

Files

License

`status` — Show node info and connection state

`list` — Show all mesh nodes

`connect <country>` — Connect to a country

`disconnect` — Remove all peers

`announce` — Re-announce to registry

`pair` — Generate/share pairing code