Quick Start (Skip to the Good Stuff)

Get RunWhen up and running in 30 minutes. Perfect for POC and evaluation.

What You'll Build

What you'll get:

• RunWhen Platform workspace (SaaS)

• RunWhen Local running in your cluster

• Automatic discovery of Kubernetes resources (within the same cluster)

• Ready-to-use troubleshooting tasks

Time required: 15 minutes

Prerequisites

Verify prerequisites:

# Check kubectl
kubectl version --client

# Check cluster access
kubectl get nodes

# Check helm
helm version

# Check you have admin access
kubectl auth can-i create clusterrole

Step 1: Create RunWhen Account (1 minute)

1. Go to https://app.beta.runwhen.com

2. Click Sign In With [Social Provider] or

   1. Enter your email and create password

Step 2: Create Workspace (10 minutes)

1. Click +ADD WORKSPACE in top right

2. Enter workspace name: my-first-workspace

3. IMPORTANT: Copy and save your workspace token

   Example token: ws_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
   

   ⚠️ Save this token securely! You'll need it in the next step.

4. Click Create Workspace

What happens:

• Workspace created in RunWhen Platform

• Unique workspace token generated

• You're now viewing your empty workspace

Step 3: Deploy RunWhen Local (5 minutes)

Now we'll deploy the RunWhen Local agent to your Kubernetes cluster.

Add Helm Repository

# Add RunWhen Helm repository
helm repo add runwhen https://runwhen-contrib.github.io/helm-charts
helm repo update

Create Namespace

# Create dedicated namespace for RunWhen Local
kubectl create namespace runwhen-local

Create Secret with Workspace Token

Replace YOUR_WORKSPACE_TOKEN with the token you saved in Step 2:

# Store workspace token as Kubernetes secret
kubectl create secret generic runwhen-workspace \
  --namespace runwhen-local \
  --from-literal=token=YOUR_WORKSPACE_TOKEN

Install RunWhen Local

# Install RunWhen Local via Helm
helm install runwhen-local runwhen/runwhen-local \
  --namespace runwhen-local \
  --set workspace.tokenSecretName=runwhen-workspace \
  --set workspace.name=my-first-workspace

Verify Installation

# Check pods are running
kubectl get pods -n runwhen-local

# Expected output:
# NAME                                READY   STATUS    RESTARTS   AGE
# runwhen-local-runner-xxx            1/1     Running   0          30s
# runwhen-local-workspace-builder-xxx 1/1     Running   0          30s

Wait for pods to be in Running status (usually 30-60 seconds).

Check Logs

# View workspace builder logs
kubectl logs -n runwhen-local -l app=workspace-builder --tail=50

# You should see:
# [INFO] Starting workspace discovery...
# [INFO] Discovering Kubernetes resources...
# [INFO] Found X namespaces, Y pods, Z services...
# [INFO] Matching resources with CodeBundles...
# [INFO] Discovery complete!

Step 4: Run Discovery (3 minutes)

RunWhen Local will automatically discover your Kubernetes resources.

Check Discovery Progress

# Follow discovery process
kubectl logs -n runwhen-local -l app=workspace-builder -f

# Press Ctrl+C when you see "Upload complete"

What's happening:

1. RunWhen Local scans your Kubernetes cluster

2. Identifies resources (namespaces, pods, deployments, etc.)

3. Matches resources with CodeBundles from the registry

4. Generates tasks for each match

5. Uploads configuration to RunWhen Platform

Step 5: Verify in Platform (2 minutes)

1. Go back to https://app.beta.runwhen.com

2. Select your workspace: my-first-workspace

3. You should now see:

   • Resources: Kubernetes namespaces, pods, services discovered

   • Tasks: Troubleshooting tasks ready to run

Expected view:

Workspace: my-first-workspace
├── Clusters
│   └── your-cluster-name
│       ├── Namespace: default
│       │   ├── Pod health check
│       │   └── Service connectivity test
│       ├── Namespace: kube-system
│       │   └── Control plane health
│       └── ...

Step 6: Run Your First Task (1 minute)

Let's test the system by running a task!

Via Web UI

1. Navigate to a namespace (e.g., default)

2. Find task: "Namespace Health Check"

3. Click Run Task

4. Watch the task execute in real-time

5. Review results

Via Natural Language (if enabled)

1. Click New RunSession

2. Type: "Show me pod health in default namespace"

3. Engineering Assistant will suggest and run relevant tasks

4. Review findings

What You've Accomplished

✅ Created RunWhen account and workspace
✅ Deployed RunWhen Local to your cluster
✅ Discovered Kubernetes resources automatically
✅ Generated troubleshooting tasks
✅ Ran your first task successfully

Next Steps

Explore Features

1. Try Different Tasks

• List failed pods in a namespace

• Check container logs

• Analyze recent events

• Test service connectivity

2. Start a RunSession

graph LR
    ALERT[Alert/Question] --> SESSION[Start RunSession]
    SESSION --> TASKS[Run Diagnostic Tasks]
    TASKS --> ANALYZE[AI Analyzes Results]
    ANALYZE --> NEXT[Suggests Next Steps]

Click New RunSession and describe a problem:

• "Pods are crashing in production"

• "Service is responding slowly"

• "Can't connect to database"

3. Invite Team Members

• Click Settings → Users

• Add teammates with appropriate roles

• They can now troubleshoot in the same workspace

Customize Discovery

By default, RunWhen discovers at the basic level. You can customize this.

View Current Configuration

# Get current workspaceInfo configuration
kubectl get configmap -n runwhen-local runwhen-workspace-info -o yaml

Customize Discovery (Optional)

Create a values.yaml file:

# values.yaml
workspace:
  name: my-first-workspace
  tokenSecretName: runwhen-workspace

# Customize discovery
discovery:
  # Level of detail: none, basic, detailed
  defaultLevelOfDetail: basic
  
  # Include only specific namespaces
  includeNamespaces:
    - production
    - staging
    - default
  
  # Exclude namespaces
  excludeNamespaces:
    - kube-system
    - kube-public
  
  # Advanced: Set per-namespace LOD
  namespaceLOD:
    production: detailed  # More comprehensive monitoring
    staging: basic

Upgrade with new configuration:

helm upgrade runwhen-local runwhen/runwhen-local \
  --namespace runwhen-local \
  -f values.yaml

Trigger new discovery:

# Delete workspace builder pod to restart discovery
kubectl delete pod -n runwhen-local -l app=workspace-builder

# Watch new discovery
kubectl logs -n runwhen-local -l app=workspace-builder -f

Add More Clusters

To monitor additional clusters, deploy RunWhen Local to each:

# On second cluster
kubectl create namespace runwhen-local
kubectl create secret generic runwhen-workspace \
  --namespace runwhen-local \
  --from-literal=token=YOUR_SAME_WORKSPACE_TOKEN

helm install runwhen-local runwhen/runwhen-local \
  --namespace runwhen-local \
  --set workspace.tokenSecretName=runwhen-workspace \
  --set workspace.name=my-first-workspace \
  --set cluster.name=my-second-cluster  # Different name!

Both clusters will report to the same workspace.

Enable Integrations

Slack Integration:

1. Platform → Settings → Integrations → Slack

2. Follow OAuth flow

3. Receive notifications in Slack

4. Run tasks from Slack: /runwhen check production namespace

Webhook from Monitoring:

1. Platform → Settings → Webhooks

2. Copy webhook URL

3. Configure in your alerting tool:

   JSON

   {
     "webhook_url": "https://app.beta.runwhen.com/webhooks/...",
     "payload": {
       "alert": "{{alert_name}}",
       "severity": "{{severity}}",
       "namespace": "{{namespace}}"
     }
   }
   

PagerDuty/Opsgenie:

• Platform → Settings → Integrations

• Connect your incident management tool

• Alerts trigger RunSessions automatically

Troubleshooting Quick Start

Problem: Pods Not Starting

# Check pod status
kubectl get pods -n runwhen-local

# Check events
kubectl get events -n runwhen-local --sort-by='.lastTimestamp'

# Describe problematic pod
kubectl describe pod -n runwhen-local <pod-name>

Common causes:

• Image pull issues (check image pull secrets)

• Resource constraints (check node capacity)

• RBAC issues (check service account permissions)

Problem: Can't Connect to Platform

# Test connectivity
kubectl exec -n runwhen-local deploy/runwhen-local-runner -- \
  curl -v https://app.beta.runwhen.com/health

# Check workspace token
kubectl get secret -n runwhen-local runwhen-workspace -o jsonpath='{.data.token}' | base64 -d

Common causes:

• Incorrect workspace token

• Firewall blocking outbound HTTPS (port 443)

• Proxy configuration needed

Problem: No Resources Discovered

# Check RBAC permissions
kubectl auth can-i list pods --all-namespaces \
  --as=system:serviceaccount:runwhen-local:runwhen-local

# Check workspace builder logs
kubectl logs -n runwhen-local -l app=workspace-builder

Common causes:

• Insufficient RBAC permissions

• No resources in included namespaces

• Discovery filters too restrictive

Get Help

Community Support:

• Slack: https://runwhen.slack.com

• GitHub: https://github.com/runwhen-contrib/codecollection-registry

Documentation:

• Full installation guide: ../installing/

• Configuration reference: ./runwhen-local/configuration.md

• Troubleshooting: ./troubleshooting.md

Upgrading to Production

Ready to move beyond POC? Here's what to consider:

1. Review Architecture

• Deployment Options

• Security Model

2. Plan Production Deployment

• Multiple clusters? Deploy RunWhen Local to each

• High availability needed? Enable HA mode

• Compliance requirements? Review security settings

3. Production Checklist

• [ ] SSO configured (not just email/password)

• [ ] Audit logging enabled

• [ ] Backup strategy for workspace config

• [ ] Monitoring of RunWhen Local pods

• [ ] Team training completed

• [ ] Escalation procedures defined

4. Follow Production Guide

➡️ Production SaaS Installation Guide

Summary

You now have:

• ✅ RunWhen Platform workspace

• ✅ RunWhen Local agent running

• ✅ Automatic resource discovery

• ✅ Troubleshooting tasks ready

• ✅ Understanding of basic operation

Congratulations! You're ready to troubleshoot with AI-powered automation.

Questions? Contact: support@runwhen.com
Ready for production? Contact: sales@runwhen.com