Glossary¶

Definitions of the terms you'll see repeated throughout this documentation and in the Web UI.

A¶

Admin mode¶

The org-wide admin area of the Web UI (/admin/*), only visible to admin users. Reached from Admin Settings under Administration in the sidebar, or by visiting any /admin/* URL. See Administration.

AMI (Amazon Machine Image)¶

The disk image AWS uses to launch EC2 instances. Waveshift's orchestrator and Kasm host run on Ubuntu 24.04 LTS AMIs; infrastructure servers and egress servers run on Amazon Linux 2023 (arm64) AMIs.

AWS (Amazon Web Services)¶

The cloud provider every Waveshift deployment runs on. Customers bring their own AWS account; Waveshift never runs in shared infrastructure.

B¶

Bearer router¶

The router that provides upstream internet to a Waveshift hardware deployment. Typically a GL.iNet Beryl, but can be any router that hands out DHCP leases on its LAN side.

Blackfire Technology¶

The company that develops Waveshift. Blackfire Technology Ltd is the contracting entity for licences and support.

Bubbletea¶

The TUI framework used to build wsctl's interactive flows. Not exposed to users directly — they just see the resulting screens.

C¶

Cloudflare WARP¶

Cloudflare's free WireGuard-based VPN service. Waveshift can optionally chain WARP behind an Egress Server so the final hop to the public internet exits from a Cloudflare IP rather than the AWS one. Toggled per Egress Server.

Console¶

The Waveshift Web UI, served by the orchestrator over HTTPS at console.<your-private-domain> (console.waveshift.internal by default). Replaces what older Waveshift documentation referred to as the WUI. See Console tour.

Control Hub¶

A GL.iNet Brume 2 router flashed with Waveshift Control-Hub firmware. The Hub is the partner-side entry point into the Waveshift network; it dials a preconfigured WireGuard tunnel to its Site's Infrastructure Access Server in AWS.

The Hub has two roles:

Management plane (always). The orchestrator pushes configuration to attached Nodes through the Hub's tunnel — WireGuard configs, Wi-Fi settings, firmware updates. The Hub is what makes a Site's Nodes reachable from the control plane.
Data plane, when Nodes are tethered to it. While a Node is physically connected to the Hub, that Node's user WireGuard tunnel to its Egress Server runs inside the Hub's tunnel (tunnel-in-tunnel). The reason is ISP fingerprint: at a single site with several Nodes, the local ISP sees one outbound endpoint (the Infrastructure Access Server) instead of one per Node, even though each Node is egressing through a different region. Once a Node is detached and operating from its own bearer somewhere else, that concern disappears and the Node talks directly to its Egress Server.

A tablet or laptop plugged into the Hub's LAN can reach console.waveshift.internal (the Waveshift Console) but not the general internet — useful for ops-room setups where a single console drives the egress fleet.

One Hub per physical Site. Adding a node site via wsctl (wsctl node-site create, or the TUI) creates the Site that the Hub and its Nodes belong to, plus the Site's Infrastructure Access Server; wsctl hub configure then binds the Hub to it — see Site and Infrastructure Access Server.

Control plane¶

The management layer of a Waveshift deployment — issues commands to the rest of the system but doesn't carry user traffic itself. Implemented by a single component, the Orchestrator, whose public face is the Console. The opposite of the data plane (the WireGuard fleet that actually carries packets).

D¶

Data plane¶

The set of components that carry user traffic — every WireGuard tunnel between Nodes, Hubs, Egress Servers, Infrastructure Servers, and (optionally) Cloudflare WARP. The opposite of the control plane, which only carries control / configuration messages.

E¶

Egress Server¶

An on-demand AWS infrastructure deployment that runs a WireGuard server in a chosen region. Optionally extended with a paired Node, Workspaces (Kasm), and a Cloudflare WARP final hop. The terms Egress Server and the older PoP (Point of Presence) refer to the same thing; v0.5 standardises on Egress Server.

Entropy¶

Randomness used to generate cryptographic keys. Waveshift generates WireGuard keys from the operating system's secure random source; an entropy helper for topping up the kernel pool on headless servers ships in the repository but isn't part of automatic provisioning yet.

F¶

Files¶

The per-user object-storage feature in the Web UI. Browse, upload, share, and delete files; storage is backed by an S3 bucket configured at deployment time. Gated by the storage licence.

Firmware¶

Software flashed onto Waveshift hardware (Control Hub, Nodes). Based on OpenWrt with Waveshift-specific modules for VPN management, automatic configuration, and the killswitch.

G¶

GL.iNet¶

Manufacturer of the routers used as Waveshift hardware: Brume 2 for the Control Hub, Slate AX for Nodes, Beryl for the Bearer.

H¶

Hub¶

Short for Control Hub.

I¶

IAM (Identity and Access Management)¶

AWS service for controlling which principals can act on which AWS resources. Waveshift creates a small set of IAM roles for the orchestrator, Kasm host, and infrastructure servers — see Defaults.

Identity provider¶

The workload-identity account (--identity-account) the orchestrator uses to authenticate to Blackfire's container registry and pull Waveshift images. Configured during wsctl config init; stored in wsctl.json as identity_account.

Infrastructure Access Server¶

A WireGuard server hosted on a public-subnet EC2 instance in the customer's AWS deployment — one per Site. The Hub for that Site dials into this server; the orchestrator uses the same tunnel to push configurations to the Site's Nodes.

The Infrastructure Access Server is not an egress server and never carries user traffic to the public internet. Its roles are:

Terminate the Hub's WireGuard tunnel so the orchestrator can configure Nodes attached to the Hub.
Be the AWS-side endpoint of any Node-to-Egress tunnel-in-tunnel traffic while a Node is tethered to the Hub (the Node's user WG tunnel runs inside the Hub's tunnel to this server, then crosses VPC peering to reach the Egress Server in its region).
Provide the path that lets a tablet plugged into the Hub reach console.waveshift.internal.

Managed in Infrastructure administration. The Web UI currently labels these "Infrastructure Servers"; canonical term in the docs is Infrastructure Access Server.

K¶

Kasm Workspaces¶

A containerised browser / desktop service that Waveshift can run on its own EC2 host. Sessions are ephemeral by default (close the workspace, the container dies); persistent profiles are an opt-in. Egress through any of your Egress Servers.

Killswitch¶

The Node's firewall rules that drop all traffic if the WireGuard tunnel is down. Prevents accidental leaks.

L¶

Licence (platform)¶

A signed JWT issued by Blackfire Technology that controls which Waveshift features are enabled and how many of each resource the deployment may run. Applied via System administration.

N¶

Node¶

A GL.iNet Slate AX router flashed with Waveshift firmware. The user-facing piece of Waveshift hardware: a user's laptops, phones, and IoT gear plug into the Node (Wi-Fi or LAN), and anything that connects through it gets routed via WireGuard to an Egress Server — no per-device VPN client needed.

The orchestrator configures Nodes through the Control Hub's management tunnel. A user picks which Egress Server a Node forwards to when they create the Egress Server in the Web UI. Traffic exits at that Egress Server in AWS, not at the Node itself — the Node is just the on-premises bridge.

Lifecycle. A Node can only be configured while it's physically attached to its Site's Hub. Once configured, the Node can be unplugged, taken anywhere, and given internet through any bearer; on the new uplink it dials its Egress Server directly. When the Egress Server it was bound to is torn down:

If the Node is back at the Hub at teardown time, it's factory-reset immediately and returned to the available pool.
If the Node is elsewhere at teardown time, the orchestrator flags it; the next time the Node is reconnected to a Hub and a user goes to configure it, it's factory-reset first before the new configuration is pushed.

A disconnected Node is not visible in the Web UI's available pool — it only appears when it's reachable through its Site's Hub.

O¶

OpenWrt¶

Open-source Linux-based firmware for routers. Waveshift's hardware firmware is OpenWrt with custom modules.

Orchestrator¶

The EC2 instance that runs Waveshift's control plane — the Go services, the Postgres database, and the Web Console. One orchestrator per deployment. Often used as a synonym for "control plane" in casual writing because there's only one of them.

P¶

P2P (peer-to-peer)¶

Direct WireGuard traffic between two clients on the same Egress Server, never traversing the public internet.

PoP (Point of Presence)¶

Older term for Egress Server; superseded in v0.5.

R¶

Region¶

An AWS region that Waveshift can deploy egress / infrastructure servers into. Regions are enabled per-deployment in Infrastructure administration.

Roundel¶

The circular Waveshift logo variant used for partner directories and avatars. See Brand assets.

Route 53¶

AWS DNS service. Waveshift creates a private hosted zone (waveshift.internal by default; configurable during the TUI) for service discovery inside the VPC. The Console and Kasm both resolve under it. The orchestrator never exposes a public HTTPS endpoint — all access is over the WireGuard network.

S¶

Site¶

An admin-managed region scope that bundles a set of allowed AWS regions and (optionally) anchors hardware. A user can belong to one or more Sites; the union of their Sites' allowed regions is what they can egress through. Physical hardware nodes are attached to a Site through their control hub — the hub's Site membership is what pins the downstream nodes to that Site's region(s).

Sites can be created two ways:

Created with a node site via wsctl — when an admin runs wsctl node-site create (or adds a node site in the TUI), the orchestrator creates a new Site and its Infrastructure Access Server; wsctl hub configure then binds the Control Hub to it. Any Nodes downstream of the Hub join the same Site by attachment. This is the path that creates hardware-anchored Sites.
Manually created in the admin UI — for software-only region scopes (e.g. a Site whose only job is to widen the available regions for a user's QR-code peers or Kasm sessions). Manual Sites have no Hub anchor.

A Site governs:

Allowed regions — which AWS regions members can egress through. This is the core thing a Site does.
Per-user limits — maximum instances and builds per user can be stored on a Site, but the orchestrator doesn't enforce them yet.

What a Site does not govern (these are per-user, on the user record, not the Site):

WireGuard tunnels, Kasm Workspaces access, and file storage. Each user record carries the licences (tunnels, workspaces, storage) that decide which of these the user can actually use; a Site just decides which regions those features can run in. (Sites also carry enable_kasm / enable_cloudflare flags, which aren't enforced yet.)

Multi-Site membership is how admins separate Node-mediated egress from software-only egress for the same user. For example: one Site (created by wsctl alongside a Hub) has Nodes the user can pair with their egress servers, inside a narrow region scope; a second Site (created manually in the admin UI) has no Nodes but a wider region scope for QR-code and Kasm egress. The user belongs to both. Traffic always exits at the egress server, never at the Hub or Node — the Node is just the device the user's LAN gear plugs into and routes through to the chosen egress server. Sites are named generically — site-a, site-b, site-c — not by purpose; the purpose is encoded in the allowed regions and which Nodes the Site contains, not the name.

For deployments without that kind of separation, admins typically create one "all regions" Site and assign every user to just that one — it's op-dependent.

Managed via Sites administration.

SSM (AWS Systems Manager)¶

AWS service for shelling into EC2 instances without SSH keys. wsctl connect uses SSM under the hood.

Storage (object)¶

The per-user file-storage feature backed by an S3 bucket. See Files above; default-quota is configured in Storage administration.

T¶

TUI¶

The terminal-UI mode of wsctl, built on bubbletea. Launched by running wsctl with no arguments — the supported way to install and operate a Waveshift deployment.

U¶

User mode¶

The user-facing variant of the Web UI sidebar (Dashboard, Egress Servers, Nodes, Files, Workspaces, Profile — Files and Workspaces appear only when the integration is enabled and the user holds the licence). Admins see the same pages (minus Workspaces) plus an Administration section.

V¶

VPC (Virtual Private Cloud)¶

The isolated AWS network Waveshift creates per region — VPC, subnets, internet gateway, security groups (the home-region VPC also gets a NAT gateway). Owned by the customer's AWS account.

VPN (Virtual Private Network)¶

Encrypted network tunnel. Every Waveshift VPN tunnel uses WireGuard.

W¶

Waveshift¶

A self-hosted VPN platform on a customer's own AWS account. WireGuard egress in any AWS region, plug-and-play hardware nodes, optional Cloudflare WARP, Kasm Workspaces, and per-user object storage, all managed from a single orchestrator.

WARP¶

See Cloudflare WARP.

WireGuard¶

A modern, fast VPN protocol using state-of-the-art cryptography (Curve25519 key exchange, ChaCha20 encryption, Poly1305 authentication, BLAKE2s hashing). Every Waveshift tunnel runs WireGuard.

Workspaces¶

See Kasm Workspaces.

`wsctl`¶

The command-line tool for installing and operating a Waveshift deployment. v0.5 is a complete rebuild of the older wavectl and ships with a bubbletea TUI for the interactive flows. See wsctl.

`wsctl.json`¶

The configuration file wsctl config init writes — AWS profile, region, private domain, identity account, service settings, and node sites. Every subsequent wsctl command reads from this file. See Configuration.

If a term you're looking for isn't here, check the FAQ or contact Blackfire.