Deploy walkthrough¶

Stand up a fresh v0.5 Waveshift deployment in your AWS account — orchestrator EC2 instance running the Web Console behind HTTPS, optionally Kasm Workspaces alongside it, and the credentials for your first admin user.

If you've done this before and want the command-only version, see Quick deploy.

Cloud only for now

Waveshift currently runs on AWS only. Other clouds and self-hosted environments are on the roadmap.

Prerequisites¶

Required	Why
AWS account authorised by Blackfire Technology	All of Waveshift's infrastructure runs here
AWS CLI with a configured profile	Used by `wsctl` for AWS API calls
AWS Session Manager Plugin	Needed for orchestrator port-forwards and SSM shells
Identity account identifier from Blackfire	Federates your AWS account so the deploy automation can run
`wsctl` binary on `PATH`	The CLI you'll be running

A laptop with the AWS CLI and wsctl is all you need on the client side — wsctl does everything else over the AWS APIs and SSM.

DNS is private — you don't need a public domain

wsctl creates a private Route 53 hosted zone inside your VPC during deploy. Pick any name you like (default waveshift.internal); the zone only resolves inside the WireGuard network and you don't need to own the domain publicly. The Console and Kasm get reached at https://console.<your-domain> and https://workspaces.<your-domain> from any client connected via a Hub, a Node, or a direct WireGuard config.

Install `wsctl`¶

Ask Blackfire for the latest release; binaries are published per-platform.

macOSLinuxWindows

brew install awscli
brew install --cask session-manager-plugin
# wsctl: drop the binary onto your PATH, then:
wsctl version

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip
unzip awscliv2.zip && sudo ./aws/install

curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb" -o session-manager-plugin.deb
sudo dpkg -i session-manager-plugin.deb

# wsctl: drop the binary onto your PATH, then:
wsctl version

msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi
# Session Manager Plugin: download from
# https://s3.amazonaws.com/session-manager-downloads/plugin/latest/windows/SessionManagerPluginSetup.exe
wsctl version

Set up your AWS profile¶

Pick whichever style of AWS authentication suits you. The TUI reads from ~/.aws/credentials or ~/.aws/config and lets you pick a profile from a list.

AWS SSOStatic IAM keys

aws configure sso --profile mycompany-dev
aws sso login --profile mycompany-dev
aws sts get-caller-identity --profile mycompany-dev

aws configure --profile mycompany-dev
aws sts get-caller-identity --profile mycompany-dev

Use a dedicated working directory¶

wsctl reads wsctl.json from the current working directory and writes deployment state back to the same file, so always work from a clean directory (the TUI's Hub firmware upgrade also looks for firmware files here):

mkdir ~/waveshift/mycompany-prod
cd ~/waveshift/mycompany-prod

Keep one directory per deployment (production, staging, lab) to keep their configuration files isolated.

Deploy via the TUI¶

wsctl

wsctl with no arguments launches the bubbletea TUI. Step through the Configure menu (Infrastructure → Waveshift → Kasm), then the Deploy menu (pick All). The same steps are available as plain commands — wsctl config init, wsctl config waveshift, wsctl config kasm --enable, wsctl deploy all — if you need to script them. A clean deploy takes roughly 10–15 minutes, dominated by VPC and NAT- gateway creation.

The full screen-by-screen walkthrough — every prompt, every field, what each traffic-light status means — lives in the wsctl section's TUI walkthrough.

After the deploy¶

Once wsctl reports a successful deploy:

Sign in. Connect to a Hub, a Node, or a WireGuard config from an Infrastructure Server, then open the Console at https://console.<your-domain> (default https://console.waveshift.internal) and sign in with the default credentials — see Defaults → Web Console. Change the password immediately from Profile → Change password.
Apply the platform licence from System administration → Platform licence. Most features (Workspaces, Storage, Cloudflare, multi-region) are gated by a JWT licence.
Enable regions from System administration → Regions so users can provision Egress Servers.
Create users from Users administration.

That's enough to start handing out access. From here, every day-to-day task lives in the Web Console — see the Console tour for what each page does.

Hardware setup (optional)¶

Skip this if you're running cloud-only.

If you've got a Waveshift hardware kit, walk through Hardware Setup for the physical cabling, then come back to the TUI to create a Site (Node Sites → A) and configure its Hub (select the site → H). (Detailed TUI screenshots for that flow coming soon.)

End-to-end the resources span both wsctl and the Console — the diagram below shows which side does what:

flowchart TD
    A["<b>wsctl</b><br/>Node Sites → A Add"] --> B[Orchestrator registers Site<br/>+ creates Infrastructure Server EC2<br/>+ generates WireGuard config]
    B --> C["<b>Console</b><br/>Sites administration —<br/>assign users to the new Site"]
    C --> D["<b>wsctl</b><br/>Node Sites → H Configure Hub<br/>(or wsctl hub configure)<br/>apply LAN + WireGuard config"]
    D --> E[Hub dials Infrastructure Server<br/>UDP 51820]
    E --> F[Workstations on the Hub LAN<br/>reach Console / Kasm / files]

The Hub never talks to the orchestrator directly — it only ever dials the Infrastructure Server EC2 in its region. That keeps the orchestrator off the user-facing data plane and means losing the orchestrator briefly doesn't drop existing Hub traffic.

Where to next¶

Console tour — every page in the Console, with screenshots.
wsctl — overview of the CLI; the detailed reference is being rebuilt for v0.5.
Defaults — every value baked into a stock deploy.
Common issues — symptoms with the first thing to check for each.