Home

SSH Proxy → Workspace Flow

This document describes the flow between SSH CLI, SSH Proxy, Identity, Provisioner, and k8shelld.
The flow is divided into three phases:

1. User Mapping & Onboarding
2. Workspace Provisioning
3. User Interaction (SSH Session)

1. User Mapping & Onboarding

sequenceDiagram
    autonumber
    participant C as SSH CLI
    participant P as SSH Proxy
    participant I as Identity Service
    participant G as GitHub (Identity Provider)

    C->>P: Open SSH connection (handshake)
    note right of P: Parse login (user~bp@addr)

    %% Key verification with GitHub
    P->>G: Retrieve user public keys (GitHub API)
    G-->>P: Return authorized_keys list
    P->>P: Verify SSH key / cert against GitHub keys

    %% Identity mapping
    P->>I: Resolve user mapping
    alt User mapped
        I-->>P: Mapping OK
    else User not mapped
        P->>I: Start onboarding (e.g. GitHub Device Flow)
        alt Onboarding successful
            I-->>P: Mapping created
        else Onboarding failed
            I-->>P: No mapping
            P-->>C: Access denied
        end
    end

Loading

2. Workspace Provisioning

sequenceDiagram
    autonumber
    participant C as SSH CLI
    participant P as SSH Proxy
    participant R as Provisioner
    participant K8s as Kubernetes

    P->>R: Get workspace for user
    alt Workspace exists
        R-->>P: Workspace {id, state}
    else Workspace missing
        P->>R: Provision workspace (blueprint, params)
        R->>K8s: Create workspace resources (Pod, PVC, Config, etc.)
        K8s-->>R: Accepted (workspaceId)
        R-->>P: Accepted {workspaceId}
    end

    note over P,R: Provisioner pushes events (stream)
    R-->>P: Scheduled
    R-->>P: Pulling images
    R-->>P: Starting
    alt Failure
        R-->>P: Failed {reason}
        P-->>C: Report failure & close
    else Running
        K8s-->>R: Pod Ready, IP, TLS cert
        R-->>P: Running {ip, tlsCert, endpoints}
    end

Loading