Architecture

MeshPOP is a 5-layer infrastructure stack. Each layer is an independent component with its own repo and PyPI package, but they work together as a unified system.

Stack Diagram

┌─────────────────────────────────────────────────┐
│                  AI / CLI                        │
│          (Claude Code, Cursor, Terminal)         │
└────────────────────┬────────────────────────────┘
                     │ MCP protocol / CLI
┌────────────────────▼────────────────────────────┐
│  Layer 3: mpop (Control Plane)                   │
│  Fleet orchestration, monitoring, 60+ MCP tools  │
│  pip install meshpop                             │
├──────────────────────────────────────────────────┤
│  Layer 2: vssh (Transport)                       │
│  Distributed SSH, file transfer, P2P tunneling   │
│  Single TCP port 48291, HMAC-SHA256 auth         │
│  pip install vssh                                │
├──────────────────────────────────────────────────┤
│  Layer 1: Wire (Network)                         │
│  WireGuard mesh VPN, NAT traversal, auto-recovery│
│  pip install meshpop-wire                        │
├──────────────────────────────────────────────────┤
│  Infrastructure                                  │
│  VPS, GPU servers, bare metal, NAS, Mac          │
└──────────────────────────────────────────────────┘

  Layer 4: MeshDB (Search)           pip install meshpop-db
  ┄ Indexes all files across all nodes, provides search + AI context ┄

  Layer 5: Vault (Secrets)           pip install sv-vault
  ┄ Identity, encryption, credential management across all layers ┄

How the Layers Connect

Wire → vssh

Wire establishes WireGuard tunnels between all nodes (full mesh, 10.99.x.x range). vssh uses these tunnels as its transport layer. If Wire is down, vssh automatically falls back to Tailscale.

vssh → mpop

mpop uses vssh internally for all remote operations. When you run mpop exec server "command", mpop calls vssh to execute it. When you run mpop deploy, mpop uses vssh PUT to transfer files.

mpop → AI

mpop exposes 60+ tools via the Model Context Protocol (MCP). AI tools like Claude Code connect to mpop-mcp and can monitor servers, deploy code, read logs, run commands — all through natural language.

MeshDB ↔ Everything

MeshDB indexes files across all nodes (via vssh). It gives AI the context to understand code, configs, and documentation across the entire mesh. Supports full-text search (SQLite FTS5) and semantic search (ChromaDB embeddings).

Vault ↔ Everything

Vault stores secrets (API keys, SSH keys, tokens) encrypted with AES-256-GCM. Other components read credentials through Vault. Master key can be split via Shamir\'s Secret Sharing for distributed backup.

Data Flow: Deploying Code

1. AI writes code (via Claude Code)
2. mpop deploy calls vssh PUT
3. vssh transfers files over Wire VPN tunnel
4. mpop exec restarts services on target nodes
5. MeshDB re-indexes the new code
6. AI verifies by reading logs via mpop logs

Data Flow: AI Troubleshooting

1. mpop heal detects problem (disk full on node g2)
2. AI reads logs via mpop logs g2 system
3. AI searches related code via meshdb search "disk cleanup"
4. AI writes fix, deploys via mpop exec g2 "cleanup.sh"
5. mpop heal confirms resolution

Security Model

Layer	Encryption
Wire	WireGuard ChaCha20-Poly1305
vssh	HMAC-SHA256 auth, 60s timestamp window
vssh P2P	TLS 1.3 (ECDHE + AES-GCM/ChaCha20)
Vault	AES-256-GCM + Argon2id key derivation
MeshDB	Read-only search (no secrets indexed)

One-line Summary

AI writes the code. MeshPOP runs it.