VPN Mesh v2

SKILL.md

---
name: vpn-mesh
description: "Turn your OpenClaw agent into a secure VPN exit node. Mesh network for agents to route traffic through peer nodes worldwide."
metadata:
  {
    "version": "0.10.0",
    "openclaw": {
      "requires": { "bins": ["wg", "wg-quick"] },
      "depends": ["sudo-tool"],
      "install": [
        {
          "id": "sudo-tool",
          "kind": "skill",
          "label": "Sudo Tool (required for WireGuard install)"
        },
        {
          "id": "wireguard",
          "kind": "system",
          "package": "wireguard-tools",
          "label": "WireGuard tools"
        }
      ],
      "post_install": "python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py setup"
    },
    "license": "MIT",
    "homepage": "https://github.com/stigg86/vpn-mesh",
    "allowed-tools": ["exec", "read", "write"]
  }
---

# 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](https://stigg86.github.io/vpn-mesh/)** — Auto-updates every 60 seconds.

---

## ⚠️ IMPORTANT: Prerequisites

**First, install the Sudo Tool (required):**

```bash
# 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

```bash
# 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
```bash
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
```bash
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
```bash
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
```bash
python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py disconnect
```
Removes all peers from config, returns to isolated mode.

### `announce` — Re-announce to registry
```bash
python3 ~/.openclaw/skills/vpn-mesh/scripts/vpn_mesh.py announce
```
Re-announces your node to the mesh registry.

### `pair` — Generate/share pairing code
```bash
# 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:

```bash
# 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:**
1. Run `vpn_mesh.py list` to see available exit nodes
2. Run `vpn_mesh.py route <node_id>` to route ALL traffic through that node
3. 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:**
```json
{
  "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:**
```bash
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:**
```bash
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:
```bash
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:**
```bash
# 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:**
```bash
sudo lsof -i :51820
sudo kill <PID>
```

## Demo Mode

The skill includes demo nodes to showcase the visualization:

```bash
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.