RunWhen Local

RunWhen Local is a tool that discovers cloud and Kubernetes infrastructure and transforms it into tailored, AI-agent-ready Skills. It operates in two modes:

1. Standalone Mode: Runs on your local machine via Docker. It is used for free, local exploration. It includes a built-in Model Context Protocol (MCP) server that allows AI agents (like Claude Code, Cursor, or Claude Desktop) to search, browse, and read your environment's tailored Skills. Note that standalone MCP is currently read-only (search, browse, and preview).
2. Connected Mode: Deployed via Helm into a Kubernetes cluster. It connects to the RunWhen Platform to provide managed, production-grade execution, including RBAC, scheduling, secret management, and auditing.

The discovery engine and generated Skills are identical in both modes; only the consumption and execution methods differ.

RunWhen Local determines the Level of Detail (LOD) for each Kubernetes namespace using a hierarchical priority system. When discovering namespaces, the system checks for configuration in a specific order, stopping at the first match found. This allows you to set broad defaults while providing granular overrides for specific namespaces or clusters.

The determination follows this priority order:

1. Namespace Annotations: The highest priority. If a namespace has the runwhen.com/lod annotation, it overrides all other configurations.
2. Context-Specific namespaceLODs: If no annotation exists, the system checks the specific context configuration for a mapping of that namespace to an LOD.
3. Global namespaceLODs: If no context-specific mapping is found, the system checks the global namespaceLODs configuration.
4. Context defaultNamespaceLOD: If no specific namespace mapping is found, the system uses the default LOD defined for that specific context.
5. Global defaultLOD: The final fallback if no other settings are found.

Priority Hierarchy:
1. Namespace Annotations (runwhen.com/lod)
2. Context-Specific namespaceLODs
3. Global namespaceLODs
4. Context defaultNamespaceLOD
5. Global defaultLOD

When RunWhen Local runs in Kubernetes with continuous discovery enabled (AUTORUN_WORKSPACE_BUILDER_INTERVAL), it automatically restarts the pod when a mounted ConfigMap or Secret changes. This is necessary because Kubernetes subPath volume mounts (used for files like /shared/workspaceInfo.yaml) are never updated in-place; the file inside the pod remains stale until the pod is recreated.

Mechanism:

1. The config_reloader.py process runs in the background.
2. It discovers mounted ConfigMaps and Secrets by reading the pod's spec.volumes.
3. It watches these objects via the Kubernetes API.
4. When a change is detected, the reloader signals the entrypoint via SIGUSR1 and exits.
5. The entrypoint terminates with exit code 1, triggering the Kubernetes Deployment controller to start a new pod with fresh mounts.

sequenceDiagram
    participant Admin
    participant API as Kubernetes API
    participant Reloader as config_reloader.py
    participant Entry as entrypoint.sh
    participant Kubelet

    Admin->>API: Update ConfigMap / Secret
    API-->>Reloader: MODIFIED watch event
    Reloader->>Reloader: Compare .data fingerprint
    Reloader->>Entry: exit 0
    Entry->>Entry: exit 1
    Kubelet->>Kubelet: Restart pod with fresh mounts

RunWhen Local matches resources to generation rules using a resourceTypes list in the rule specification.

Historically, matching required an exact string match between the name requested in a rule and the name stored by the indexer. The system has transitioned to an alias-aware, registry-driven matching model to support both legacy and canonical names.

The Matching Mechanism

1. Requested Name: A rule (e.g., in a rw-cli-codecollection) requests a type like azure_compute_virtual_machines.
2. Resolver: The PlatformHandler.get_resources method uses a resolver to map the requested name to an accepted-name set (match_names) within the resource Registry.
3. Union Matching: A resource matches a rule if the rule's requested type exists anywhere within that resource's match_names set, regardless of which specific name the indexer used for storage.

Fallback Behavior

For platforms not in a cloud registry (e.g., Kubernetes custom resources or the azure_devops platform), the system falls back to exact-string equality matching.

spec:
  platform: azure
  generationRules:
    - resourceTypes: [azure_compute_virtual_machines]
      matchRules: [...]
      slxs: [...]

RunWhen Local provides specialized secret patterns for Robot Framework to handle GCP authentication and GKE kubeconfig generation automatically.

Service Account Patterns

• CLI Authentication: gcp:sa@cli
• Kubeconfig Generation: gcp:sa@kubeconfig:CLUSTER_NAME/ZONE_OR_REGION (supports both zonal and regional patterns)

Application Default Credentials (ADC) Patterns

• CLI Authentication: gcp:adc@cli
• Kubeconfig Generation: gcp:adc@kubeconfig:CLUSTER_NAME/ZONE_OR_REGION

*** Settings ***
Library    RW.Core

*** Test Cases ***
GCP Service Account Example
    Import Secret    gcp_projectId
    Import Secret    gcp_serviceAccountKey
    Import Secret    my_gke_kubeconfig
    Shell    kubectl get nodes

Multi Environment Example
    # Production environment
    Import Secret    prod_gke_kubeconfig     # gcp:sa@kubeconfig:prod-cluster/us-east1
    
    # Staging environment  
    Import Secret    staging_gke_kubeconfig  # gcp:sa@kubeconfig:staging-cluster/us-west1
    
    Shell    kubectl --kubeconfig=${prod_gke_kubeconfig} get nodes