/opt/splicevpn/README.md
# SpliceVPN
Peer-to-peer, multi-endpoint mesh VPN. Run the agent on each machine, answer a few
questions, and every endpoint is connected to every other endpoint over an encrypted
overlay — with a coordinator/relay you supply as the always-available fallback.
> **Status: MVP foundation.** This is a working control-plane + mesh bring-up built on
> WireGuard. It is *not* production-hardened. See "Security" and "Roadmap" below before
> putting it anywhere real.
---
## Why it's built this way
The product promises encryption and tunnelling. **We do not implement our own crypto or
tunnel transport** — that is the single most dangerous thing a VPN can do. Instead
SpliceVPN rides on **WireGuard**: audited Noise-protocol crypto, a fast in-kernel data
plane (userspace fallback via `wireguard-go`), and roaming endpoints. Everything
SpliceVPN adds is *orchestration around* WireGuard — which is where the actual product
value (mesh, zero-config, supplied relay, bonding) lives.
```
┌──────────────────────────────────────────────┐
│ COORDINATOR (you supply) │
│ • node registry + overlay-IP assignment │
│ • hands every node the full mesh peer list │
│ • observes public src ip:port (STUN-lite) │
│ • runs a WireGuard HUB = relay fallback │
└───────────────▲───────────────▲────────────────┘
│ register/poll │
┌──────────┘ └──────────┐
│ │
┌────────┴────────┐ ┌────────┴────────┐
│ AGENT A │ ◄── direct WG ──► │ AGENT B │
│ host or /24 net │ (falls back to │ host or /24 net │
└────────┬────────┘ hub if blocked) └────────┬────────┘
│ │
└──────────────► AGENT C ◄───────────────┘
full mesh: every node peers with every node
```
## Feature → implementation map
| Promise on the site | Mechanism | State |
|---|---|---|
| Encrypted point-to-point tunnel | WireGuard peer link | MVP |
| Endpoint = a host **or** a whole network | advertised subnets → WireGuard `AllowedIPs` + routes | MVP |
| **Many endpoints all connected (mesh)** | coordinator distributes full peer list; agent configures a peer per node | MVP |
| Always finds a path (direct → … → relay) | direct mesh via discovered endpoints + coordinator-observed public mapping (STUN-lite); catch-all hub peer wired in | MVP = direct + public-mapping assist; **UDP hole-punching and DERP-style relay-on-failure = Phase 2** |
| Zero-config | `agent` wizard: coordinator URL + join key + host/subnet + profile | MVP |
| Bond multiple internet links | `linkmanager` multipath layer | **Phase 2** |
| Any port, UDP/TCP, multi-port | transport wrapper + WG-over-TCP/443 via relay | **Phase 2** |
## Layout
```
splicevpn/
proto/ shared wire types (register, peer, mesh snapshot)
coordinator/ the registry + relay-hub control plane (HTTP API)
agent/ per-endpoint client: keygen, register, render+apply WireGuard mesh
linkmanager/ Phase-2 bonding interface (stub + design notes)
```
## Build
Requires Go 1.22+, and on agents the WireGuard tools (`wg`, `wg-quick`).
```
cd splicevpn
go mod tidy
go build -o bin/splice-coordinator ./coordinator
go build -o bin/splice-agent ./agent
```
## Run
**Coordinator** (on a box with a public/LAN-reachable IP — this is your "supplied gateway"):
```
SPLICE_JOIN_KEY=[REDACTED]