Skip to content

User guide introduction

This section explains the parts that make up a Waveshift deployment and how they fit together. It's written to give you a mental model of the system rather than a step-by-step install walkthrough — for that, see Deploy walkthrough.

What's covered

  • How Waveshift works — the runtime story: user → Node → Egress Server → internet, with WireGuard at every hop and optional Cloudflare WARP at the end.
  • Cloudflare integration — what Cloudflare WARP adds when it's enabled, and what trade-offs it brings.
  • Architecture overview — the control-plane / data-plane split, the role of the orchestrator, the saga model used to provision AWS resources.
  • AWS infrastructure — what Waveshift creates in your AWS account and how it's organised.

Key concepts

A Waveshift deployment splits cleanly into a control plane and a data plane:

  • Control plane — the management layer. Issues commands, holds the database, serves the Web Console. Doesn't carry user traffic.
  • Data plane — WireGuard tunnels between Nodes and Egress Servers (and an optional Cloudflare WARP final hop). Carries the actual user packets.

The control plane is implemented by a single concrete component:

  • Orchestrator — the EC2 instance that runs the control plane. One per deployment. Its public face is the Console (the Web UI).

The data plane is built out of:

  • Egress Server — an on-demand WireGuard server in the AWS region of your choice. User traffic exits the internet through this.
  • Node — a GL.iNet Slate AX router flashed with Waveshift firmware. The on-premises device users plug their LAN hardware into; routes that traffic through WireGuard to an egress server. No per-device VPN client needed.

Two more components sit on the management side, plus they do double-duty for the data plane when Nodes are tethered to a Hub:

  • Hub — a GL.iNet Brume 2 router flashed with Waveshift firmware. Dials a preconfigured WireGuard tunnel into its Site's Infrastructure Access Server. Always carries orchestrator-to-Node management traffic. Also carries user Node-to-Egress tunnels in nested form (tunnel-in-tunnel) while a Node is physically attached — that way the local ISP sees one outbound endpoint regardless of how many Nodes are co-located. A tablet plugged into the Hub's LAN can reach console.waveshift.internal but not the general internet.
  • Infrastructure Access Server — the AWS-side WireGuard server that the Hub dials into. One per Site, hosted in the public subnet of the customer's AWS deployment.

A Site is the organisational glue between the two planes — an admin-defined region scope and (optionally) a Hub + Nodes bundle. Hubs (and the Nodes that attach to them) belong to exactly one Site, but a user can belong to several Sites at once. That lets admins, for example, give the user one Site that includes Nodes (anchored to a narrow region scope) plus a second Site with no Nodes but wider regions for QR-code or Kasm egress. Traffic always exits the Waveshift network at an Egress Server — the Node is the on-premises bridge, never the exit point. All Egress-to-internal-service traffic crosses AWS VPC peering, never the public internet. (Whether the user can use tunnels, Kasm Workspaces, or file storage at all is a per-user licence concern, not a Site concern.)

The Glossary has the full list.

Where to next