Skip to content

Waveshift Deployment Checklist

Complete step-by-step guide for deploying Waveshift from initial setup to a fully operational system with Kasm Workspaces.

About This Checklist

This checklist covers the complete deployment workflow with expandable sections containing commands and detailed instructions. Progress is saved automatically in your browser.

1. Initial Laptop Setup

  • New Linux laptop ready
  • Internet connectivity confirmed
Install wavectl and Dependencies 
# Download wavectl binary (get latest version from Blackfire Technology)
# Place in /usr/local/bin or ~/bin

# Set execute permissions
chmod +x /path/to/wavectl

# Verify installation
wavectl --version

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

# Verify AWS CLI
aws --version

# Install AWS 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

# Verify Session Manager Plugin
session-manager-plugin

2. Create Project Directory

  • Project directory created
  • Changed to project directory
Project Setup Commands 
# Create deployment directory
mkdir ~/waveshift-deployment
cd ~/waveshift-deployment

# Verify you're in the correct directory
pwd

3. AWS CLI Authentication

  • AWS CLI configured with credentials
  • Authentication verified
AWS Authentication 
# Configure AWS CLI (choose one method)

# Method 1: AWS SSO Login
aws configure sso --profile <aws-profile-name>
# Follow prompts to authenticate

# Login with SSO (required each time session expires)
aws sso login --profile <aws-profile-name>

# Method 2: AWS Access Keys
aws configure --profile <aws-profile-name>
# Follow prompts to authenticate

# Verify authentication
aws sts get-caller-identity --profile <aws-profile-name>

# Should return your account details

4. wavectl init

  • wavectl init executed successfully
  • wavectl.json created
Initialize Waveshift Configuration 
# Initialize wavectl configuration
wavectl init --identity-provider <provider-name> \
             --region <aws-region> \
             --profile <aws-profile> \
             --kasm-instance-type <instance-type> # defaults to m6a.2xlarge


# Example:
wavectl init --identity-provider my-provider \
             --region eu-west-2 \
             --profile default

# Verify configuration file created
ls -la wavectl.json
cat wavectl.json | jq .

Required information from Blackfire Technology:

  • Identity provider name

5. wavectl deploy

  • wavectl deploy executed
  • Deployment completed successfully (~10-15 minutes)
  • No errors in output
Deploy Waveshift Infrastructure 
# Deploy Waveshift to AWS
wavectl deploy

# This will create:
# - VPC and networking (subnets, IGW, NAT Gateway, route tables)
# - Security groups
# - IAM roles and instance profiles
# - Route53 private hosted zone (waveshift.internal)
# - Waveshift Control Plane EC2 instance
# - Kasm Workspaces EC2 instance
# - RDS PostgreSQL database

# Monitor deployment progress in terminal
# Wait for "Deployment complete" message

# Verify deployment
cat wavectl.json | jq '{vpc_id, waveshift_instance_id, kasm_instance_id}'

6. Create Access Server

  • wavectl access-servers --add 1 executed
  • Access server created successfully
Add Access Server 
# Create Access Server for Control Hub connectivity
wavectl access-servers --add 1

# This creates a WireGuard access server that Control Hubs connect to
# Configuration will be saved to wavectl.json

7. Register Site

  • wavectl sites --add 1 executed
  • Site registered successfully
Register Physical Site 
# Register a site for hardware routers
wavectl sites --add 1

# This registers a physical location where you'll have:
# - 1 Control Hub (GL.iNet Brume2)
# - Multiple Nodes (GL.iNet Slate AX)

# Site will be assigned site number 0
# Additional sites can be added: wavectl sites --add <number>

# Verify site registration
cat wavectl.json | jq '.sites'

8. Configure Control Hub

  • Control Hub physically connected and powered on
  • Control Hub has internet access
  • wavectl configure-hub --site 0 executed successfully
Configure Control Hub Router 
# Before running this command:
# 1. Connect Control Hub WAN port to internet source
# 2. Power on Control Hub
# 3. Ensure Control Hub is accessible on network (default: 10.34.0.1)

# Configure the Control Hub for site 0
wavectl configure-hub --site 0

# This will:
# - SSH into the Control Hub
# - Apply WireGuard configuration
# - Configure networking and DHCP
# - Enable device scanner
# - Set up time synchronisation
# - Connect Control Hub to Access Server

# Hub will be associated with site 0
# Nodes will auto-register with this Control Hub

9. Connect to Waveshift via wavectl proxy

  • Proxy connection established
  • Waveshift console accessible
Access Waveshift Console via Proxy 
# Start proxy to Waveshift console
wavectl proxy

# This creates an SSH tunnel to the Waveshift instance
# Access console at: http://localhost:8080 (or specified port)

# Default credentials:
# Username: admin
# Password: admin123

# Verify deployment:
# - Check dashboard loads
# - Verify no error messages
# - Check sites are visible

10. Connect via Control Hub

  • Connected to Control Hub network
  • Waveshift console accessible at http://console.waveshift.internal
  • Console functioning correctly
Access via Control Hub 
# Connect device to Control Hub LAN port or WiFi

# Open browser to:
http://console.waveshift.internal

# This should show the Waveshift console
# Verify:
# - Console loads correctly
# - Can see registered sites
# - Nodes appear if connected

11. Adjust Control Hub Date/Time (if needed)

  • Control Hub date/time checked
  • Adjusted if necessary
Change Date/Time via SSH

Commands to SSH into Control Hub and change date/time settings 

# SSH into Control Hub root@10.34.<site-number>.1 e.g. site 0
ssh root@10.34.0.1

# Default password Waveshift2025!

# Update date and time to now
date -s "YYYY-MM-DD HH:MM:SS"

# Verify date and time are correct
date

12. Change Kasm Admin Password

  • Kasm admin password changed
  • New password recorded securely
Update Kasm Admin Credentials

Steps to change default Kasm admin password

  1. Login to Kasm with default credentials
  2. Navigate to: Admin→Access Management→Users
  3. Click on admin user
  4. Click on Reset Password (Key Icon)
  5. Enter new password and confirm.

13. Add Kasm License

  • Kasm admin console accessed
  • License added successfully
Add Kasm Workspaces License

Steps to add license to workspaces.waveshift.internal

  1. Access Kasm admin console at: http://workspaces.waveshift.internal (via VPN/Control Hub)
  2. Login with default admin credentials
  3. Navigate to: Admin→Diagnostics→System Info→Licenses
  4. In the Licenses Tab, click + Add License
  5. Paste in the license provided by Backfire Technology

14. Add Container Images

  • Kasm admin console accessed
  • First container images added
Add Workspace Container Images

Steps to add container images via Kasm admin console

  1. Access Kasm admin console at: http://workspaces.waveshift.internal (via VPN/Control Hub)
  2. Login with default admin credentials
  3. Navigate to: Admin→Workspaces→Registry→Available Workspaces
  4. Select required workspaces and click Install
  5. Common images to add:
Chrome
Firefox
Signal
Telegram
Terminal
Ubuntu Noble
Tor-Browser

15. Configure Egress Provider Overrides

  • Egress provider overrides configured on containers
Set Up Egress Provider Overrides

Complete For Each Container Image

Steps to configure egress provider overrides for each container

  1. Access Kasm admin console at: http://workspaces.waveshift.internal (via VPN/Control Hub)
  2. Login with default admin credentials
  3. Navigate to Admin→Workspaces→Workspaces
  4. Select > (Arrow Icon) on right side of desired workspace
  5. Click Edit (Pencil Icon)
  6. In the Edit tab, scroll to Override Egress Gateways and toggle on
  7. Scroll back to the top and select Egress tab
  8. Click + Add (Opens **Configure Egress dialog)
  9. Ensure Enabled is toggled on
  10. Select waveshift from Egress Provider drop-down
  11. Ensure Allow all Gateways is toggled on
  12. Click Save
  13. Return to the Edit tab
  14. Click Save at the bottom of the page

Repeat the above process for all workspaces

16. Configure Persistent Profiles

  • Persistent profiles set up on containers
Enable Persistent Profiles

Complete For Each Container Image

Steps to configure persistent profiles for each container

  1. Using the terminal navigate to the deployment directory containing wavectl.json
  2. run the following command: 
    cat wavectl.json | jq {s3_bucket_name}
  3. Copy the s3_bucket_name that is output e.g. 123456789123456-waveshift-workspaces-persistent-profiles
  4. Access Kasm admin console at: http://workspaces.waveshift.internal (via VPN/Control Hub)
  5. Login with default admin credentials
  6. Navigate to Admin→Workspaces→Workspaces
  7. Select > (Arrow Icon) on right side of desired workspace
  8. Click Edit (Pencil Icon)
  9. In the Edit tab, scroll to Persistent Profile Path and paste in the following:

replace S3_BUCKET_NAME with the output from the previous command

s3://S3_BUCKET_NAME/{username}/{image_id}/
  • Click Save at the bottom of the page

Repeat the above process for all workspaces

17. Configure Kasm Agent Cores/Memory

  • Cores overrides configured
  • Memory overrides configured
Adjust Kasm Agent Resources

Steps to configure CPU and memory overrides for Kasm agents

  1. Access Kasm admin console at: http://workspaces.waveshift.internal (via VPN/Control Hub)
  2. Login with default admin credentials
  3. Navigate to Admin→Infrastructure→Docker Agents
  4. Select > (Arrow Icon) on right side of proxy agent
  5. Click Edit (Pencil Icon)
  6. Adjust Cores Override and Memory Override based on instance size and expected workload
  7. Click Save at the bottom of the page

Cores and Memory Values

Each Kasm workspaces is set to use 2 Cores and 2768MB Memory by default. Adjust the proxy agent Cores and Memory to a value that will allow the maximum number of containers to run on the instance you set during wavectl init, whilst maintaining a stable user environment.

Agent memory is set in bytes so 10Gb = 10737418240

Leaving Memory and Cores at default values of 0 will use the actual available memory and cores on the EC2 instance

Adjusting these values too high will result in a poor user experience during high usage

Not enough resources to start session

An error message along these lines will be shown when attempting to launch a session if not enough memory is available at the time of launching a workspace.

Either attempt to launch at a later time during lower usage or increase the amount of avialable memory through:

  1. editing agent settings, Cores Override and Memory Override
  2. increasing the EC2 instance size
  3. configuring autoscalling. Advanced

18. Connect Waveshift Nodes to Control Hub

  • Nodes LAN2 ports physically connected to Control Hub
  • Nodes WAN port physically connected to internet bearer (optional)
  • Nodes powered on
Confirm nodes are populating on waveshift console

Steps to confirm nodes are populating on waveshift console

  1. Access waveshift console at: https://waveshift.waveshift.internal (via VPN/Control Hub) or http://localhost:8080 (via wavectl proxy)
  2. Login with default admin credentials
  3. Navigate to Nodes
  4. Confirm nodes are populating (may take a few minutes)

!!! note "Nodes may take a few minutes to populate if just powered on. Refresh page if necessary.

Deployment Complete!

Verification Checklist

  • All steps above completed
  • Waveshift console accessible
  • Control Hub connected and functioning
  • Kasm Workspaces accessible and licensed
  • Container images available
  • Egress providers configured
  • Admin passwords changed
  • Nodes populating on waveshift console
  • Regions added to sites
  • Test user created & deleted
  • Confirmitory PoPs created, tested and destroyed

Documentation References

Support

Email: support@blackfire.tech
Documentation: https://docs.waveshift.io