Quick Start Guide¶

Get Waveshift deployed quickly with these command-focused workflows. For detailed explanations, see the Deploying Waveshift guide.

Prerequisites

AWS CLI configured and authenticated
wavectl binary installed
Blackfire identity provider access
Working in a clean, dedicated directory

Scenario 1: Basic Deployment (Console Access Only)

Deploy Waveshift infrastructure and access via wavectl proxy.

# Create working directory
mkdir waveshift-deployment && cd waveshift-deployment

# Login to AWS (SSO)
aws sso login --profile my-aws-profile

# Initialize configuration
wavectl init --identity-provider my-provider --profile my-aws-profile --region eu-west-2

# Deploy infrastructure
wavectl deploy

# Access Waveshift Console
wavectl proxy
# Opens http://localhost:8080

Result: Waveshift deployed, accessible via proxy.

Credentials: admin / admin123

Scenario 2: Deployment with Control Hub

Deploy with one access server and configure one control hub router.

# Create working directory
mkdir waveshift-deployment && cd waveshift-deployment

# Login to AWS
aws sso login --profile my-aws-profile

# Initialize and deploy
wavectl init --identity-provider my-provider --profile my-aws-profile --region eu-west-2
wavectl deploy

# Create access server
wavectl access-servers --add 1

# Register site (performs health check, may take up to 15 mins)
wavectl sites --add 1

# Configure hub router (must be connected and flashed)
wavectl configure-hub --site 0

Result: Control hub configured for Site 0, connected via Access Server 0.

Router Requirements

Router must be flashed with Waveshift firmware
Router must be physically connected to your device
Only configure ONE hub per site

Scenario 3: Deployment with Hub + Direct WireGuard Access

Deploy with two access servers: one for control hub, one for direct WireGuard client access.

# Create working directory
mkdir waveshift-deployment-client-x && cd waveshift-deployment-client-x

# Login to AWS
aws sso login --profile aws-example-profile

# Verify authentication
aws sts get-caller-identity --profile aws-example-profile

# Initialize configuration
wavectl init --identity-provider aws-my-provider --profile aws-example-profile --region eu-west-2 --kasm-instance-type t3a.medium

# Deploy infrastructure (~10-15 minutes)
wavectl deploy

# Create two access servers
wavectl access-servers --add 2

# Register one site (assigned to Access Server 0)
wavectl sites --add 1

# Get WireGuard config for direct access (Access Server 1)
wavectl access-servers --wg-config 1
# Copy output to WireGuard client

# Configure hub router for Site 0
wavectl configure-hub --site 0

Result: - Control hub configured on Site 0 (via Access Server 0) - WireGuard client config for direct access (via Access Server 1)

Access Methods:

wavectl proxy: wavectl proxy → http://localhost:8080
Control Hub: Connect to hub → http://console.waveshift.internal
WireGuard: Load config → http://console.waveshift.internal

WireGuard Single Connection

Only ONE device can use each access server WireGuard config at a time. Do not share or use simultaneously.

Scenario 4: Multi-Site Deployment

Deploy with multiple sites and control hubs.

# Setup
mkdir waveshift-multi-site && cd waveshift-multi-site
aws sso login --profile my-aws-profile

# Initialize and deploy
wavectl init --identity-provider my-provider --profile my-aws-profile --region us-east-1
wavectl deploy

# Create access servers (one per site)
wavectl access-servers --add 3

# Register sites
wavectl sites --add 3

# Configure hub routers
wavectl configure-hub --site 0
wavectl configure-hub --site 1
wavectl configure-hub --site 2

Result: Three sites with three control hubs, each connected via dedicated access server.

Site-to-Access-Server Assignment

Sites are assigned to access servers sequentially:

Site 0 → Access Server 0
Site 1 → Access Server 1
Site 2 → Access Server 2

Common Commands¶

Check Deployment Status¶

# View configuration
cat wavectl.json

Get WireGuard Configs¶

# Get config for specific access server
wavectl access-servers --wg-config 0
wavectl access-servers --wg-config 1

Configure Additional Hubs¶

# Default router IP (10.34.0.1)
wavectl configure-hub --site 0

Access Waveshift¶

# Quick proxy access
wavectl proxy

# Start SSM session to controller
wavectl start-session waveshift

# Start SSM session to Kasm
wavectl start-session kasm

# Start SSM session to access server
wavectl start-session access_server_0

Default Credentials¶

Service	URL	Username	Password
Waveshift Console	http://console.waveshift.internal	admin	admin123
Kasm Workspaces	https://workspaces.waveshift.internal	admin	Waveshift2025!
Control Hub Router	http://10.34.0.1	root	Waveshift2025!

Change Default Passwords

Always change default passwords immediately after first login.

Quick Troubleshooting¶

Authentication Errors:

aws sts get-caller-identity --profile my-profile

Services Not Ready: - Wait 10-15 minutes after wavectl deploy before running wavectl sites --add - The sites command includes automatic health checking

Router Configuration Fails: - Verify router is flashed with Waveshift firmware - Check router is connected (ping 10.34.0.1) - Ensure router has default credentials

Can't Access Console: - Verify WireGuard/hub connection is active - Try wavectl proxy for quick access - Check you're using correct internal domain

Next Steps¶

Deploying Waveshift - Detailed deployment guide with explanations
CLI Reference - Complete command documentation
Default Values & Credentials - Full reference of defaults
Troubleshooting - Detailed troubleshooting guide

Getting Help¶

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