K8shell Workspace Identifier

A compact identifier in the SSH user@address form that encodes:

• The user initiating the connection
• An optional workspace blueprint (direct name or parameters)
• Optional parameters for provisioning or inspecting the workspace

The SSH proxy parses the WID to determine the correct Kubernetes workspace to inspect or provision.

Grammar

WID        = local "@" addr
local      = user [ "~" ws-spec ]
ws-spec    = bp-name / param-list

param-list = kv *( "+" kv )
kv         = key "=" value

user       = 1*(atext / "." / "_" / "-")
bp-name    = 1*(atext / "." / "_" / "-" / "/")
key        = 1*(lower-alpha / digit / "-")
value      = *(atext / "." / "_" / "-" / "/" / "%")
addr       = 1*(VCHAR)   ; your SSH host or alias

; atext (RFC 5322) roughly: A–Z a–z 0–9 and ! # $ % & ' * + - / = ? ^ _ ` { | } ~

Reserved delimiters: @ ~ + =
Escape mechanism: Use percent-encoding for reserved characters inside values.

Encoding Rules

• user and ws-spec are separated by ~.
• If ws-spec contains no =, treat it as a direct blueprint name.
• If ws-spec contains =, parse as key=value pairs, separated by +.
• / is allowed in bp-name and value, but:
  • If an environment (e.g., VS Code CLI) cannot handle raw /, replace with %2F.
• Percent-encode:
  • % → %25
  • ~ → %7E
  • + → %2B
  • = → %3D
  • Any reserved or unsafe character that must appear literally.

Examples

Direct blueprint

tomas~dev@edge.k8shell.io
→ user = tomas  
→ bp   = dev

Repo + ref with raw slash

tomas~repo=k8shell-io/identity+ref=main@edge.k8shell.io
→ user = tomas  
→ repo = k8shell-io/identity  
→ ref  = main

Repo with escaped slash (CLI-safe)

tomas~repo=k8shell-io%2Fidentity+ref=main@edge.k8shell.io
→ repo = k8shell-io/identity  
→ ref  = main

Multiple params

tomas~repo=org/svc+ref=feat%2Fabc+mode=inspect@edge
→ repo = org/svc  
→ ref  = feat/abc  
→ mode = inspect

Hierarchical blueprint name

tomas~teamA/blueprints/prod@edge
→ bp = teamA/blueprints/prod

Allowed Characters

• In user, bp-name, value:
  Letters, digits, . _ - / and RFC5322 atext specials (!#$%&'*+-/=?^_{|}~`).
• Avoid , ; : ( ) [ ] \ " < > — percent-encode if needed.
• If @ is needed inside a value, percent-encode as %40.

Length Guidance

• local (before @) ≤ 64 characters (mirrors common email limits).
• Total WID ≤ 128 characters for wide tool compatibility.

Compatibility Notes

• SSH / VS Code Remote: Works if / is percent-encoded when necessary.
• Email-style parsers: RFC-compliant local part.
• Linux usernames: Do not reuse local directly as a Unix account name.
• Kubernetes labels/annotations: If storing params in labels, follow label value restrictions ([A-Za-z0-9_.-], ≤63 chars) or use annotations for raw WID.