Deploying Waveshift - Complete Walkthrough¶

Supported Waveshift deployments

Currently Waveshift is only supported on AWS.

In the future we aim to support deploying waveshift to other cloud providers and locally hosted environments.

Simple Step-by-Step Deployment & Checklist

Follow the comprehensive Installation Checklist for a complete step-by-step deployment walkthrough from initial setup to fully configured Waveshift instance with Kasm Workspaces.

Default Workspaces Admin Password Update

Since Waveshift v0.4.0 the default admin password for Kasm Workspaces has been updated to Waveshift2025!
This change only takes effect when deploying waveshift with the latest version.
It does not get updated when the service is upgraded.

Quick Start - Advanced

Looking for command-only deployment workflows? See the Quick Start Guide for multiple deployment scenarios with minimal explanation.

Prerequisites¶

AWS Account - Required for deploying Waveshift to and its basic function.
AWS CLI - Required for AWS operations and SSM sessions
AWS Session Manager Plugin - Required for SSM port forwarding and sessions
Blackfire Provider - Required for deploying waveshift
wavectl binary - Installed to your path

Setup AWS Dependencies

AWS Documentation Reference

The following AWS setup instructions provide a quick overview for getting started with wavectl. For comprehensive and up-to-date information about AWS CLI configuration, authentication methods, and best practices, please refer to the official AWS CLI documentation.

LinuxmacOSWindows

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

# Install Session Manager Plugin
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

# Install AWS CLI
brew install awscli

# Install Session Manager Plugin
brew install --cask session-manager-plugin

# Install AWS CLI
msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi

# Install Session Manager Plugin
# Download and run: https://s3.amazonaws.com/session-manager-downloads/plugin/latest/windows/SessionManagerPluginSetup.exe

AWS Setup and Authentication¶

Initial AWS CLI Setup¶

First, install and configure the AWS CLI:

AWS IAM UserAWS SSO

# Configure AWS CLI with your credentials
aws configure

# Or configure a named profile
aws configure --profile my-company-dev

You'll be prompted for:

AWS Access Key ID: Your AWS access key
AWS Secret Access Key: Your AWS secret key
Default region name: e.g., us-east-1, eu-west-2
Default output format: json (recommended)

AWS Profile Configuration¶

Creating Named Profiles¶

Create multiple profiles for different environments or accounts:

# Production profile
aws configure --profile my-company-prod
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-east-1
Default output format [None]: json

# Development profile  
aws configure --profile my-company-dev
AWS Access Key ID [None]: AKIAI44QH8DHBEXAMPLE
AWS Secret Access Key [None]: je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
Default region name [None]: eu-west-2
Default output format [None]: json

Manual Profile Configuration¶

Alternatively, edit ~/.aws/credentials and ~/.aws/config directly:

~/.aws/credentials:

[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[my-company-prod]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[my-company-dev]
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY

~/.aws/config:

[default]
region = us-east-1
output = json

[profile my-company-prod]
region = us-east-1
output = json

[profile my-company-dev]
region = eu-west-2
output = json

#Configure AWS CLI with your SSO credentials
aws configure sso --profile profile-name

You'll be prompted for:

SSO session name (Recommended): example-session
SSO start URL [None]: e.g. https://example.awsapps.com/start/#
SSO region [None]: The region where your SSO is configured in. e.g. eu-west-2
SSO registration scopes [sso:account:access]: sso:account:access

After which you will be directed to login to authenticate via a browser.

Once authenticated, return to the CLI and choose the desired account and role you wish to set up. If there is only one option, this will be chosen for you.

You will now be prompted to setup the AWS profile:

Default client Region [None]: e.g. eu-west-2
CLI default output format (json if not specified) [None]: json

Verify Profile Configuration¶

Test your profiles:

# Test default profile
aws sts get-caller-identity

# Test named profile
aws sts get-caller-identity --profile my-company-dev

# List all configured profiles
aws configure list-profiles

Authentication Methods¶

wavectl supports multiple authentication methods:

AWS SSO (Single Sign-On) (Recommended for organisations)¶

# Login to AWS SSO
aws sso login --profile my-company-dev

# Verify SSO login
aws sts get-caller-identity --profile my-company-dev

Named AWS Profiles (Recommended for individual use)¶

Use --profile flag with wavectl commands
Profiles stored in ~/.aws/credentials and ~/.aws/config

Default AWS Profile¶

Used when no --profile specified
Configured via aws configure

Environment Variables¶

export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_DEFAULT_REGION=us-east-1

IAM Roles (When running on EC2)¶

Automatic credential retrieval from instance metadata
No manual configuration required

Deploy Waveshift¶

AWS Authentication Required

Before proceeding, ensure you are authenticated with AWS via the CLI.

If using AWS SSO, ensure you are logged in first (for IAM based profiles skip this step):

aws sso login --profile my-aws-profile

Verify your authentication status by running:

# using the default aws profile
aws sts get-caller-identity

# or if using a named aws profile
aws sts get-caller-identity --profile my-aws-profile

Use a Dedicated Directory

All wavectl commands should be run from a dedicated, clean directory. The wavectl.json configuration file will be created in your current working directory and is essential for managing your deployment. Create a new directory for each Waveshift deployment to keep configurations organised and avoid conflicts.

mkdir my-waveshift-deployment && cd my-waveshift-deployment

Getting Help

The --help flag can be used with any wavectl command or subcommand to display detailed usage information and available options.

# General help
wavectl --help

# Command-specific help
wavectl init --help
wavectl deploy --help
wavectl access-servers --help
wavectl sites --help
wavectl configure-hub --help
wavectl proxy --help
wavectl start-session --help

Step 1: Initialise Configuration¶

Before deploying infrastructure, initialise the wavectl configuration file with your AWS settings:

# Initialise with identity provider and profile using the default region set in the profile
wavectl init --identity-provider my-blackfire-provider-name --profile my-aws-profile-name --kasm-instance-type t3a.medium

# Or with specific region
wavectl init --identity-provider my-blackfire-provider-name --region us-east-1 --profile my-aws-profile-name

# Using environment variables (no profile needed)
wavectl init --identity-provider my-blackfire-provider-name

This creates a wavectl.json configuration file that stores your AWS profile, region, and other settings for use by all subsequent wavectl commands.

Step 2: Deploy Infrastructure¶

Deploy the complete Waveshift infrastructure to AWS. This process typically takes 10 minutes and creates all necessary AWS resources.

# Deploy with settings from wavectl.json (created by wavectl init)
wavectl deploy

What Gets Deployed

What Gets Deployed¶

During deployment, you'll see progress for:

1. VPC and Networking

New VPC with public and private subnets
Internet Gateway and NAT Gateway
Route tables and security groups
Elastic IP allocation

2. IAM Roles and Policies

Waveshift controller role with comprehensive AWS permissions
Kasm workspaces role for EC2 access
Instance profiles for EC2 instances

3. Route53 DNS

Private hosted zone (waveshift.internal)
DNS records for internal service discovery

4. EC2 Instances

Waveshift Controller (t3a.medium): Main orchestration platform
Kasm Workspaces (m6a.2xlarge default, unless otherwise specified): Containerized desktop environments

5. SSM Parameter Store

Secure API key storage
Configuration parameters

Step 3: Create Your First Access Server¶

Access servers are public wireguard servers that allow you to connect to your waveshift controller from anywhere.

wavectl access-servers --add 1

This creates:

EC2 WireGuard access server in the public subnet of the VPC
Access server credentials

Step 4: Create Your First Site (Only required if using Waveshift Nodes)¶

Site Configuration

An access server must be created prior to a site being created.

Health Check

When wavectl sites is run, a health check is performed on the waveshift server. This ensures that the server is running and responsive before creating the site registration. It is normal for this to take up to 15 minutes if run nearly immediately after wavectl deploy.

This creates a site registration in Waveshift and assigns that site to an access server for configuring a control hub router. Sites are assigned to access servers configs in the wavectl.json sequentially. access-server-0:site-0 ...

# Create one additional site
wavectl sites --add 1

# Add multiple additional sites
wavectl sites --add 3

This creates: - Site registration in Waveshift - Updates wavectl.json with site details

Step 5: Configure Control Hub (Only required if using Waveshift Nodes)¶

Router Configuration

A site must have been registered using wavectl prior to configuring a router

Router Configuration

The router must have already been flashed with the latest waveshift router firmware. If not, the configuration will fail.

Router Configuration

Ensure that only one hub is configured to each site at any one time. Failure to do so will result in undefined behavior.

Router Configuration

The router must be connected to the device running wavectl in order to be configured.

This will configure the connected router as a Control Hub for the specified site and filled with the associated credentials toconnect to waveshift via the access server assigned to that site.

wavectl configure-hub --site 0

Router Configuration

The router will reset and reboot after configuration to apply changes. This will be indicated by its LED.

Step 6: Access Waveshift¶

Access via wavectl Proxy¶

As a wavectl user it is possible to access the Waveshift Console quickly using the wavectl proxy command. This is useful for quick troubleshooting without the need to connect your device to a Control Hub or via an access server.

This is usually a good SOP prior to accessing the system via any other method in order to ensure that Waveshift is working.

wavectl proxy

This will create a reverse proxy to the Waveshift Console and open it in your default browser via http://localhost:8080

Standard Waveshift Access

Using the methods below, Waveshift can be accessed via your browser using:

Waveshift Console: http://console.waveshift.internal

Kasm Workspaces: https://workspaces.waveshift.internal

Access via Control Hub¶

If you have a Control Hub configured, you can access the Waveshift Console via the Control Hub.

Internet Connection

Ensure that the Control Hub is connected to the internet via its WAN port.

Internet Connection

Currently the control hub will not be able to connect to waveshift via an internet bearer that is connected to a VPN. This causes a MTU mismatch and the connection will fail. We aim to fix this in a coming release.

Access via Wireguard Client to Access Server¶

If you have an access server configured, you can access the Waveshift Console via the access server using the resulting wireguard config for that server.

The config can be retrieved witht he following command:

wavectl access-servers --wg-config <access-server-number>

This can then be loaded into your devices wireguard client.

Wireguard Configuration

Ensure that no other devices are using the same access-server config simultaneously. The access-servers are designed for a single connection and will not function correctly if multiple devices are using the same config.

If using the same config that a control hub would be using in order to perform debugging, ensure that the control routers internet connection has been severed.

Deployment Complete

You can now access Waveshift via the methods above.

Waveshift Console - default admin username: admin - default admin password: admin123

Kasm Workspaces - default admin username: admin - default admin password: Waveshift2025!

Configuration Files¶

Default Configuration Location¶

wavectl uses wavectl.json in the current directory, there can be only one deployment config per directory.

Configuration Structure¶

{
  "access_servers": [
    {
      "access_ec2_instance_id": "i-xxxxxxx",
      "access_ec2_private_ip": "10.32.0.115",
      "access_ec2_public_ip": "11.22.33.44",
      "access_ec2_wg_pubkey": "e58aEuL0zAY9wN9++Ng1+K4MjtId0VOZsxxxxxxx=",
      "access_server_number": 0,
      "control_hub": {
        "cidr": "10.34.0.0/24",
        "ip_address": "10.34.0.1",
        "wg_private_key": "IMhq5odkoLC0ktTRcOQqiAC6MkVYp/p5sxxxxxxx=",
        "wg_public_key": "5dcA/gLl2rJYoxk+3l+tKEntvXRDWsvE+7xxxxxxx="
      },
      "wg_preshared_key": "7BeKRhSWdbe4S77v7QYiI3VOz0q4xxxxxxx="
    }
  ],
  "availability_zone": "eu-west-2a",
  "cloudwatch_logs_domain_name": "logs.eu-west-2.amazonaws.com",
  "cloudwatch_logs_endpoint_id": "vpce-xxxxxxx",
  "cloudwatch_logs_hosted_zone_id": "/hostedzone/xxxxxxx",
  "eip_allocation_id": "eipalloc-xxxxxxx",
  "hosted_zone_id": "/hostedzone/xxxxxxx",
  "identity_account": "xxxxxxx",
  "internet_gateway_id": "igw-xxxxxxx",
  "kasm_instance_id": "i-xxxxxxx",
  "kasm_instance_type": "t3a.medium",
  "kasm_private_ip": "10.32.1.156",
  "main_route_table_id": "rtb-xxxxxxx",
  "nat_gateway_id": "nat-xxxxxxx",
  "orchestration_service_api_key": "xxxxxxx",
  "private_domain": "waveshift.internal",
  "private_sg_id": "sg-xxxxxxx",
  "private_subnet_id": "subnet-xxxxxxx",
  "profile": "my-aws-profile",
  "public_route_table_id": "rtb-xxxxxxx",
  "public_sg_id": "sg-xxxxxxx",
  "public_subnet_id": "subnet-xxxxxxx",
  "region": "eu-west-2",
  "s3_bucket_arn": "arn:aws:s3:::xxxxxxx-waveshift-workspaces-persistent-profiles",
  "s3_bucket_name": "xxxxxxx-waveshift-workspaces-persistent-profiles",
  "sites": [
    {
      "site_number": 0,
      "site_id": "xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx",
      "access_server_number": 0
    }
  ],
  "ssm_policy_arn": "arn:aws:iam::xxxxxxxxxxxx:policy/waveshift-ssm-policy",
  "vpc_endpoint_sg_id": "sg-xxxxxxx",
  "vpc_id": "vpc-xxxxxxx",
  "waveshift_access_role_arn": "arn:aws:iam::xxxxxxxxxxxx:role/waveshift_access_role",
  "waveshift_controller_profile_arn": "arn:aws:iam::xxxxxxxxxxxx:instance-profile/waveshift_controller_profile",
  "waveshift_controller_role_arn": "arn:aws:iam::xxxxxxxxxxxx:role/waveshift_controller_role",
  "waveshift_instance_id": "i-xxxxxxx",
  "waveshift_kasm_profile_arn": "arn:aws:iam::xxxxxxxxxxxx:instance-profile/waveshift_kasm_profile",
  "waveshift_kasm_role_arn": "arn:aws:iam::xxxxxxxxxxxx:role/waveshift_kasm_role",
  "waveshift_private_ip": "10.32.1.5",
  "wg_access_profile_arn": "arn:aws:iam::xxxxxxxxxxxx:instance-profile/waveshift_wg_access_profile"
}

Next Steps¶

Now that you have Waveshift running:

Explore the Platform¶

User Guide: Learn about system architecture and operations
CLI Reference: Master advanced wavectl commands
Architecture Guide: Understand the system design

Scale Your Deployment¶

Add more sites with wavectl sites --add N
Configure additional hub routers
Set up monitoring and logging

Customize Configuration¶

System Requirements: Review hardware and software requirements
Troubleshooting: Resolve common deployment issues

Troubleshooting¶

Quick Checks:

# Verify AWS authentication
aws sts get-caller-identity

# Check deployment status
cat wavectl.json

# Test router connection (hub setup)
ssh root@10.34.0.1

Detailed Help

For comprehensive troubleshooting, see the Troubleshooting Guide.

Cleanup, Removal and Destruction¶

Waveshift Managed Infrastructure

Before destroying the main infrastructure using wavectl, you must first clean up all infrastructure that Waveshift has deployed during operation. E.g. VPC regions and running Egress Servers. This prevents orphaned AWS resources that could continue incurring costs.

Destruction Order

For the moment, a strict order of destruction must be adhered to. A fix will be released to enable a simple complete destruction procedure. - Delete all Waveshift egress PoPs - Remove/Delete all Waveshift users - Delete/Disable all Waveshift regions - Destroy all access-servers using wavectl access-servers --destroy all - Destroy all main infrastructure using wavectl deploy --destroy all

wavectl deploy --destroy all

The wavectl deploy --destroy all command will destroy all AWS resources that wavectl has deployed during the wavectl deploy operation. This will remove all EC2 instances, VPC and networking components, IAM roles and policies, Route53 hosted zones, SSM parameters, and all associated AWS resources.

wavectl access-servers --destroy all

The wavectl access-servers --destroy all command will destroy all AWS resources that wavectl has deployed during the wavectl access-servers operation. This will remove all EC2 instances, VPC and networking components, IAM roles and policies, Route53 hosted zones, SSM parameters, and all associated AWS resources.

wavectl Infrastructure Destruction

Ensure that you are not connected to any Waveshift resources before destroying the infrastructure. This will cause the operation to hang and potentially result in failure to delete all resources.

Destructive Procedures

These commands are destructive operations and will permanently delete all related AWS resources. Ensure you have backups of any important data before proceeding.

Delete remaining resources from AWS after wavectl deploy --destroy all

EIP that was associated to the Waveshift NAT-Gateway does not get deleted.
VPC and Subnets are not deleted.
These must be deleted manually via AWS Console or awscli.