wavectl.json Configuration¶

Primary configuration file created by wavectl init and used by all commands. All subsequent commands read their AWS profile, region, and other settings from this file, eliminating the need to specify these flags repeatedly.

Configuration Structure¶

{
  "region": "us-east-1",
  "identity_provider": "aws-my-company-dev",
  "profile": "my-company-dev",
  "kasm_instance_type": "m6a.2xlarge",
  "instance_id": "i-1234567890abcdef0",
  "kasm_instance_id": "i-0987654321fedcba0",
  "sites": [
    {
      "site_number": 0,
      "wg_private_key": "...",
      "wg_public_key": "...",
      "wg_preshared_key": "..."
    }
  ]
}

Key Benefits¶

One-time setup: Configure AWS profile and region once during wavectl init
Consistent configuration: All commands use the same AWS profile and region
Simplified usage: No need to remember or specify --profile and --region flags
Persistent state: Configuration and infrastructure state stored in single file

Configuration Fields¶

Core Settings¶

Field	Description	Set By
`region`	AWS region for deployment	`wavectl init`
`identity_provider`	GCP workload identity provider name	`wavectl init`
`profile`	AWS profile to use	`wavectl init`
`kasm_instance_type`	Kasm instance type	`wavectl init`

Infrastructure State¶

Field	Description	Set By
`instance_id`	Main Waveshift instance ID	`wavectl deploy`
`kasm_instance_id`	Kasm workspace instance ID	`wavectl deploy`
`vpc_id`	VPC ID	`wavectl deploy`
`private_domain`	Internal DNS domain	`wavectl deploy`
`api_key`	Generated API key	`wavectl deploy`

Site Configuration¶

Field	Description	Set By
`sites`	Array of site configurations	`wavectl sites`
`sites[].site_number`	Sequential site number	`wavectl sites`
`sites[].wg_private_key`	WireGuard private key	`wavectl sites`
`sites[].wg_public_key`	WireGuard public key	`wavectl sites`
`sites[].wg_preshared_key`	WireGuard preshared key	`wavectl sites`

Default Location¶

The configuration file is created in the current working directory as wavectl.json.

Multiple Environments¶

For managing multiple deployments (e.g., production, staging), use separate directories:

# Create separate directories for each environment
mkdir ~/waveshift-production ~/waveshift-staging

# Initialize each environment in its own directory
cd ~/waveshift-production
wavectl init --identity-provider prod-provider --profile prod-profile --region us-east-1

cd ~/waveshift-staging
wavectl init --identity-provider staging-provider --profile staging-profile --region us-west-2

Security Considerations¶

Sensitive Information¶

The configuration file contains sensitive information:

AWS profile names
WireGuard private keys
API keys
Infrastructure resource IDs

Best Practices¶

File Permissions: Restrict access to the configuration file
Version Control: Add wavectl.json to .gitignore
Backup: Keep secure backups of configuration files
Environment Separation: Use separate directories for different environments

# Secure file permissions
chmod 600 wavectl.json

# Add to .gitignore
echo "wavectl.json" >> .gitignore

Troubleshooting¶

Configuration Not Found¶

# Verify file exists in current directory
ls -la wavectl.json

# Check current directory
pwd

# wavectl looks for wavectl.json in the current directory
cd /path/to/your/deployment/directory

Invalid Configuration¶

# Validate JSON syntax
cat wavectl.json | jq .

# Check required fields
cat wavectl.json | jq '{region, identity_provider, profile}'

Corrupted Configuration¶

# Backup current config
cp wavectl.json wavectl.json.backup

# Re-initialise if needed
wavectl init --identity-provider aws-my-company-dev --region us-east-1 --profile my-company-dev

Migration¶

Updating Configuration Format¶

When wavectl is updated, the configuration format may change. The tool will automatically migrate older formats when possible.

Manual Migration¶

If manual migration is needed:

Backup: Create a backup of the current configuration
Re-initialise: Run wavectl init with the same parameters
Restore State: Manually copy infrastructure state from backup if needed