`wsctl.json` reference¶

The configuration file wsctl writes to the current working directory the first time you save the Configure → Infrastructure form in the TUI (or run wsctl config init). Every subsequent wsctl command reads it for AWS profile / region / identity account, and writes deployment state back to the same file.

TUI-first

Don't hand-edit wsctl.json. The TUI keeps it in sync with the deployed AWS resources, and edits that don't match the schema can leave a deployment in a state wsctl can't read. Use wsctl config show to inspect, and the TUI to make changes.

Shape¶

{
  "version": "1.0",
  "state": "KASM_DEPLOYED",
  "aws": {
    "region": "us-east-1",
    "profile": "mycompany-dev"
  },
  "infrastructure": {
    "configured": true,
    "deployed": true,
    "domain": "waveshift.internal",
    "identity_account": "aws-mycompany-dev",
    "vpc_id": "vpc-0abc1234",
    "public_subnet_id": "subnet-0aaa1111",
    "private_subnet_id": "subnet-0bbb2222"
  },
  "waveshift": {
    "configured": true,
    "enabled": true,
    "deployed": true,
    "subdomain": "console",
    "instance_type": "t3a.small",
    "instance_id": "i-0123456789abcdef0",
    "api_version": "dev-latest",
    "frontend_version": "dev-latest"
  },
  "kasm": {
    "configured": true,
    "enabled": true,
    "deployed": true,
    "subdomain": "workspaces",
    "instance_type": "m6a.2xlarge",
    "instance_id": "i-0fedcba9876543210"
  },
  "infra_server_settings": {
    "region": "us-east-1",
    "name_prefix": "node site",
    "instance_type": "t4g.nano"
  },
  "infra_servers": [ … ],
  "sites": [ … ]
}

The example is trimmed — after a deploy each section also holds the IDs of the AWS resources wsctl created (route tables, security groups, hosted zone, IAM ARNs, S3 bucket names, private IPs, and so on).

Top-level sections¶

`version`, `state`¶

version is the config schema version (1.0). state is recalculated by wsctl on every save and tracks how far the deployment has got: UNINITIALIZED, INFRA_CONFIGURED, INFRA_DEPLOYED, WAVESHIFT_CONFIGURED, WAVESHIFT_DEPLOYED, KASM_CONFIGURED, KASM_DEPLOYED (shown in the TUI as Fully Deployed).

`aws`¶

Field	Type	Set by	Notes
`region`	string	TUI / `wsctl config init`	The AWS region the orchestrator and Kasm host run in
`profile`	string (optional)	TUI / `wsctl config init`	AWS profile in `~/.aws/config` or `~/.aws/credentials`. If unset, the AWS SDK's default credential chain is used

`infrastructure`¶

Field	Type	Set by	Notes
`configured`	boolean	TUI / `wsctl config init`	True after the base settings are saved
`deployed`	boolean	TUI	True after VPC / IAM / Route 53 / S3 / CA are live
`domain`	string	TUI / `wsctl config init`	Private Route 53 zone name; Console and Kasm resolve under it (default `waveshift.internal`)
`identity_account`	string	TUI / `wsctl config init`	Federated identity account issued by Blackfire
`vpc_cidr`, `public_subnet_cidr`, `private_subnet_cidr`	string	defaults	`10.32.0.0/23`, `10.32.0.0/24`, `10.32.1.0/24`
`vpc_id`, `public_subnet_id`, `private_subnet_id`, `nat_gateway_id`, `hosted_zone_id`, …	string	TUI (after deploy)	AWS resource IDs created during the infrastructure deploy
`assets_bucket_name`, `filestore_bucket_name`	string	TUI (after deploy)	S3 buckets for certificates/profiles and for user files
`api_key`	string	TUI (after deploy)	Orchestrator API key generated during the infrastructure deploy

`waveshift`¶

The orchestrator service block. Created the first time you configure the Waveshift service.

Field	Type	Set by	Notes
`configured`, `enabled`, `deployed`	boolean	TUI	Lifecycle flags. `enabled` controls whether Deploy → All includes the service
`subdomain`	string	TUI / `wsctl config waveshift`	Defaults to `console`
`instance_type`	string	TUI / `wsctl config waveshift`	Defaults to `t3a.small`
`instance_id`, `private_ip`	string	TUI (after deploy)	EC2 instance ID and private IP
`api_version`, `frontend_version`	string	TUI / `wsctl config waveshift`	Container image versions. Default `dev-latest`

`kasm`¶

Same shape as waveshift, without the image-version fields and with s3_bucket_name / s3_bucket_arn for the Kasm profiles bucket. Only present once Kasm has been configured. Defaults: subdomain: "workspaces", instance_type: "m6a.2xlarge". enabled defaults to true in the TUI form and to false when created with wsctl config kasm (pass --enable to opt in).

`infra_server_settings`¶

Defaults the TUI's Node Sites screen uses for new Infrastructure Servers: region (falls back to aws.region), name_prefix (default node site), and instance_type (default t4g.nano).

`sites`¶

Array of registered Sites. Each Site has a site_number (used for the Hub's 10.34.<site_number>.0/24 addressing), the orchestrator's site_id, the infra_server_id it pairs with, and — once a Hub is configured — the Hub's mac_address.

`infra_servers`¶

Array of WireGuard Infrastructure Servers. Each Site usually pairs with one Infrastructure Server in the same region; the link is the Site's infra_server_id (and the server's associated_sites). Each entry also holds the server's WireGuard public key, preshared key, and the control_hub block with the Hub's WireGuard keypair and address.

Multiple deployments¶

Keep one directory per deployment so their wsctl.json files don't clash:

mkdir ~/waveshift/prod
mkdir ~/waveshift/staging
cd ~/waveshift/prod && wsctl
cd ~/waveshift/staging && wsctl

Security¶

wsctl.json contains:

AWS profile names (not secrets, but identifying)
AWS resource IDs (VPC, subnets, instances)
WireGuard private and preshared keys for Hubs / Infrastructure Servers
The orchestrator API key (infrastructure.api_key)

Treat it as sensitive:

chmod 600 wsctl.json (wsctl writes it as 0644)
Add to .gitignore; do not commit
Keep secure backups outside the repo

wsctl.json reference¶

Shape¶

Top-level sections¶

version, state¶

aws¶

infrastructure¶

waveshift¶

kasm¶

infra_server_settings¶

sites¶

infra_servers¶