How Waveshift works¶

Waveshift is a self-hosted VPN platform that combines hardware nodes, cloud infrastructure, and privacy features to give a team secure, controlled internet access and a private mesh between their devices.

Looking for a quick visual answer?

The Key questions section has single-page answers to "what does the full network look like?", "how is attribution managed?", "how is an Egress Server provisioned?", and more — each with a v0.5 diagram. This page is the deeper conceptual reference.

System overview¶

A Waveshift deployment splits cleanly into a control plane (management; doesn't carry user traffic) and a data plane (WireGuard tunnels; does carry user traffic).

Control plane¶

Orchestrator¶

The single EC2 instance that implements the control plane. Runs the Web Console, holds the database, dispatches work to the data plane, and exposes the API that wsctl and the Console talk to. One per deployment.

Data plane¶

Control Hub¶

A GL.iNet router flashed with Waveshift firmware that manages and coordinates the Nodes at a Site. It's the bridge between the Site's local Nodes and the orchestrator-side Infrastructure Server in AWS.

Nodes¶

Configurable GL.iNet routers (Slate AX) flashed with Waveshift firmware. Nodes let non-Waveshift devices join the VPN by providing local network connectivity with automatic VPN routing on the WAN side.

Egress Servers¶

On-demand WireGuard servers in the AWS region of your choice. Provisioned by the orchestrator on request; this is where internet traffic exits.

Sites and multi-region¶

v0.5 introduces two concepts that the original Proteus model didn't have: Sites and a per-Site Infrastructure Access Server (IAS).

Sites¶

A Site is a logical scope. It has a UUID, a human-readable name, an AllowedRegions list, and feature flags such as EnableCloudflare. It does not have AWS resources of its own — a Site is a database row that governs what regions its users can provision Egress Servers in, and which optional features those users get.

There are two flavours in practice:

Hub Sites — created when an admin adds a node site with wsctl node-site create (or the TUI equivalent). The Site's IAS is provisioned at the same time, and wsctl hub configure then onboards the Control Hub to it.
The Default Site — auto-created on first deploy with the well-known UUID 4DA40066-0EF8-493C-A1B6-F51A8C714A15 and the name "Global". It has no Hub. Users assigned to the Default Site provision Egress Servers and connect a WireGuard client directly — no Node, no Hub, no tunnel-in-tunnel.

A user can belong to multiple Sites and pick which scope to use when provisioning an Egress Server.

Infrastructure Access Server (IAS)¶

The IAS is a per-Site WireGuard endpoint that lives in the AWS public subnet of the Site's home region. A Control Hub dials its Site's IAS and keeps a long-lived management tunnel up; the orchestrator reaches the Hub through that tunnel to push Node configs, deploy firmware, and read Node status.

When a tethered Node carries user traffic, that user-WG traffic is wrapped inside the Hub→IAS tunnel — this is the tunnel-in-tunnel behaviour. From the local ISP's perspective, the Site only opens one outbound UDP/51820 flow per Hub, regardless of how many devices are on the LAN.

Multi-region¶

Egress Servers live in a per-region VPC (shared by every Egress Server in that region) that only peers back to the home region (star topology). Spokes never peer with each other. This keeps the blast-radius of any one region contained and makes adding new regions cheap (one new VPC + one new peering connection).

For the full network view with every CIDR and peering relationship, see Key questions → Network overview.

Network Architecture¶

Physical Network Topology¶

The Waveshift network connects local devices through a layered architecture:

Local Area Network (LAN)
Nodes provide LAN connectivity for user devices
Devices connect via Ethernet to the nodes
All traffic is automatically routed through secure WireGuard tunnels
Control Hub connection
Control Hub connects to the internet via a Bearer router
Creates a WireGuard tunnel to the Site's Infrastructure Server in AWS, which bridges control traffic into the orchestrator
Nodes connect to both the Control Hub (for management) and the internet (for data)
Multiple Internet Circuits
Each node should ideally have its own internet circuit with unique egress IP
This maintains privacy by preventing traffic correlation

Egress Server (Egress Server) Architecture¶

What is a Egress Server?¶

A Egress Server is an on-demand AWS infrastructure deployment that provides: - WireGuard VPN server with unique public IP - Optional Cloudflare WARP integration for traffic normalisation - Optional Kasm Workspaces integration for secure browsing - Private peer-to-peer connectivity between devices

Egress Server Provisioning Process¶

When a user provisions a Egress Server through the Waveshift console:

User Configures Egress Server via web interface, selecting:
Egress location (AWS region)
Enable/disable Node integration
Enable/disable Kasm Workspaces
Enable/disable Cloudflare WARP final egress
Number of additional WireGuard peer configs
Orchestrator provisions infrastructure:
Deploys EC2 instance in the selected AWS region
Configures the WireGuard server
Generates peer configurations
Sets up security groups and networking
Configuration Distribution:
WireGuard configs made available via QR codes or files
Nodes automatically configured if Node integration enabled
Kasm workspace automatically configured if enabled

Egress Server Build Sequence¶

The automated build process follows a specific sequence:

Node Configuration and Connectivity¶

Automatic Node Configuration¶

When an Egress Server is built with Node integration enabled:

The orchestrator selects an unassigned Node from the pool
WireGuard configuration is automatically deployed to the Node
Firewall rules and the VPN killswitch are configured
The Node becomes associated with the Egress Server

Node Internet Connectivity¶

Nodes provide secure internet access for connected devices:

Device connects to Node LAN port
Traffic is routed through WireGuard tunnel on the node
VPN killswitch ensures no traffic leaks if tunnel fails
Traffic egresses through the Egress Server's public IP address
Optional Cloudflare WARP provides additional anonymisation

Data Flow Overview¶

Basic Traffic Flow¶

graph LR
    A[User Device] -->|Ethernet| B[Node LAN]
    B -->|WireGuard Tunnel| C[AWS Egress Server]
    C -->|Optional Cloudflare| D[Public Internet]

Detailed Data Path¶

Traffic Flow Steps:

User device connects to Node via Ethernet
Node encrypts all traffic with WireGuard
Traffic traverses internet through Node's circuit
AWS Egress Server decrypts WireGuard traffic
If Cloudflare disabled: Traffic egresses directly from Egress Server
If Cloudflare enabled: Traffic re-encrypted and sent to Cloudflare WARP
Cloudflare WARP decrypts and sends to public internet
Response follows reverse path

Cloudflare WARP Integration¶

Why Integrate Cloudflare WARP?¶

Waveshift uses a hybrid approach combining AWS Egress Servers with Cloudflare WARP to provide:

Benefits of AWS Egress Servers: - Full control over infrastructure - Choose specific egress location - No shared VPN IP addresses - Transparent operation

Benefits of Cloudflare WARP: - Massive anonymity set (millions of users) - Shared exit IPs - Traffic normalisation - Additional layer of encryption

Traffic Normalisation¶

By routing through Cloudflare WARP:

Your traffic is encrypted by WireGuard to AWS Egress Server
AWS Egress Server forwards to Cloudflare WARP server
Cloudflare sees traffic originating from AWS (not your real IP)
Internet sees traffic coming from Cloudflare shared IP
Your origin is protected by two layers of anonymisation

This is what we call traffic normalisation - your traffic blends into millions of other Cloudflare WARP users, making it extremely difficult to identify or track.

Anonymity Set Comparison¶

Service	Anonymity Set Size	Shared Exit IPs	Your Control	Use Case
Waveshift (AWS only)	Very small (just you)	No	Full	Private dedicated access
Waveshift + Cloudflare	Very large (millions)	Yes	High	Anonymous normalized access
Cloudflare WARP alone	Very large (millions)	Yes	None	Limited to nearby regions
Commercial VPN	Large	Yes	None	General anonymity

Cloudflare Integration Sequence¶

sequenceDiagram
    participant Client
    participant Orchestrator
    participant Egress as AWS Egress Server
    participant Cloudflare

    Client->>Orchestrator: Request WG + Cloudflare config
    Orchestrator->>Egress: Provision (saga)
    Note right of Orchestrator: Peer public keys in user data
    Egress->>Cloudflare: Register device (WGCF)
    Note right of Egress: Egress Server public key provided to Cloudflare
    Cloudflare-->>Egress: Device registration response
    Egress-->>Orchestrator: Server WG public key
    Egress-->>Orchestrator: WireGuard instance built
    Note right of Orchestrator: Egress Server public key via SSM Parameter Store
    Orchestrator-->>Client: WireGuard peer config

    Client->>Egress: Connect via WireGuard
    Egress->>Cloudflare: Forward via WARP
    Note right of Cloudflare: Authenticate & route
    Cloudflare-->>Internet: Normalised traffic

Peer-to-Peer Networking¶

Devices on the same Egress Server can communicate directly and securely:

Private VPN network between all peers on the same Egress Server
End-to-end encryption via WireGuard
No internet exposure for P2P traffic
Multi-device collaboration possible

Use Cases: - File sharing between trusted devices - Remote desktop access - Private gaming servers - Secure team collaboration

Kasm Workspaces Integration¶

What is Kasm?¶

Kasm Workspaces provides containerized browser environments for secure web browsing.

Waveshift + Kasm¶

When Kasm integration is enabled on a Egress Server:

The user's Kasm account (created when they're given the Workspaces licence) is used
Browser workspace is automatically configured with Egress Server as egress provider
All browser traffic routes through the selected Egress Server location
Isolated environment protects your main device
Destroy when done - all traces removed

Benefits: - Browser fingerprinting resistance - Sandboxed environment - No local trace of activity - Easy egress location switching

Security Features¶

Encryption¶

WireGuard protocol for VPN tunnels (Curve25519, ChaCha20)
End-to-end encryption between device and Egress Server
No logging of traffic by default
Forward secrecy protects past communications

Privacy Features¶

VPN killswitch on nodes prevents leaks
No DNS leaks - all DNS via WireGuard tunnel
Firewall rules block non-VPN traffic
Unique egress IPs per Egress Server (no sharing)
Traffic normalisation via Cloudflare (optional)

Entropy and Key Generation¶

WireGuard keys are generated from the operating system's cryptographically secure random source (Go's crypto/rand in the orchestrator, wg genkey on servers).

The repository also ships an entropy helper that mixes externally supplied entropy with local system entropy and injects it into the kernel pool, for headless cloud servers. It isn't part of automatic provisioning yet.

Deployment Flexibility¶

Multiple Egress Locations¶

Deploy Egress Servers in any AWS region worldwide
Switch between locations instantly
Multiple active Egress Servers simultaneously
Each Egress Server is independent

Scalability¶

Per-Egress Server peer slots: chosen when provisioning (1–20 in the Console). The licence JWT carries a wireguard_clients quota, but the orchestrator doesn't enforce it yet.
Egress Servers per user: limited by the user's Site membership and AllowedRegions. A user with the Default Site can provision in any allowed region.
Regions per deployment: every additional AWS region adds one VPC (/23 from the 10.32.0.0/16 map) and one peering connection back to the home region. There's no hard cap, just AWS quotas.
Organisation limits: per-Site region allowlists are set by admins.
On-demand provisioning: saga-driven, retry-safe, sub-five- minute provisioning and sub-minute teardown.

Summary¶

Waveshift provides:

✅ Privacy - Multi-layer anonymisation with traffic normalisation
✅ Control - Choose exact egress locations worldwide
✅ Flexibility - Nodes, direct configs, or Kasm workspaces
✅ Security - Strong encryption, killswitches, isolated environments
✅ Simplicity - Hardware that works out of the box
✅ Scalability - From single user to organisation-wide deployments