Quick Start

This guide gets you from zero to a working RunWhen workspace in about 30 minutes. It’s the fastest way to see the platform in action on your own cluster.

What You’ll End Up With

A RunWhen workspace connected to one Kubernetes cluster
Automatic discovery of your namespaces, deployments, and services
Hundreds of troubleshooting tasks matched to your resources
Workspace Chat ready for natural-language investigations

Prerequisites

Requirement	Details
Kubernetes cluster	v1.23 or later, with `kubectl` access
Helm 3.x	Install Helm
Cluster admin	Temporary — needed for RBAC setup during install
RunWhen account	Sign up at app.beta.runwhen.com (Google, GitHub, GitLab, or email)

Verify prerequisites

kubectl version --client
kubectl get nodes
helm version
kubectl auth can-i create clusterrole

Step 1 — Create Your Workspace (5 min)

Sign in at app.beta.runwhen.com.
For new accounts the Create your first Workspace wizard opens automatically. Enter a workspace name (e.g. my-workspace).
Choose your Privacy / Accuracy preference (Balanced is a good default).
Click Continue. The platform provisions your workspace and shows you the Helm install command for the next step.

If you already have a workspace and want to add another one, click the + button in the bottom-left corner of the platform UI.

Workspaces are automatically cleaned up (all data removed) after 14 days of inactivity.

Step 2 — Deploy RunWhen Local (10 min)

The Helm chart installs two pods into a dedicated runwhen-local namespace:

runwhen-local-workspace-builder — discovers resources and matches them with tasks
runwhen-local-runner — executes tasks and sends results to the platform

Add the Helm repo

helm repo add runwhen https://runwhen-contrib.github.io/helm-charts
helm repo update

Install

The workspace wizard provides a ready-to-use helm install command. You can also construct it manually:

helm install runwhen-local runwhen/runwhen-local   --namespace runwhen-local   --create-namespace   --set workspaceName=my-workspace   --set runner.enabled=true

Verify

kubectl get pods -n runwhen-local

# Expected:
# runwhen-local-workspace-builder-xxx   1/1   Running   60s
# runwhen-local-runner-xxx              1/1   Running   60s

Step 3 — Confirm Discovery (5 min)

The workspace builder starts scanning your cluster automatically. Watch its progress:

kubectl logs -n runwhen-local -l app.kubernetes.io/name=runwhen-local-workspace-builder --tail=50 -f

Once you see discovery complete, go back to the platform. Your workspace should now show discovered resources, matched tasks, and be ready for Workspace Chat.

Step 4 — Try It Out

Open Workspace Chat and ask something about your cluster:

“What is the health of my cluster?”
“Are any pods crashing?”
“Show me recent events in the default namespace”

The assistant will pick relevant tasks, execute them via the runner in your cluster, and return findings with recommended next steps.

What’s Next


Add more clusters	Deploy the Helm chart to each cluster with the same workspace name. See SaaS Installation for multi-cluster details.
Customize discovery	Adjust which namespaces are scanned and at what level of detail using `values.yaml`. See the Helm chart reference.
Set up rules & commands	Teach the assistant about your environment’s quirks. See Use for details.
Invite your team	Settings → Users. Everyone shares the same workspace and assistant context.
Connect integrations	Slack, webhooks, SSO. See Configure.

Troubleshooting

Issue	Fix
Pods not starting	`kubectl describe pod -n runwhen-local <pod>` — check for image pull or resource issues
No resources discovered	Check workspace builder logs and RBAC: `kubectl auth can-i list pods --all-namespaces --as=system:serviceaccount:runwhen-local:workspace-builder`
Runner can’t connect	Verify outbound HTTPS to `runner.beta.runwhen.com` (port 443). Check proxy settings if applicable.

Need help? Contact support@runwhen.com