Install

This section walks you through connecting RunWhen to your Kubernetes clusters. Pick the path that matches your situation.

Choose Your Path

Path	Best For	Time	Link
Quick Start	First-time evaluation, single cluster, want to see value fast	~30 min	Quick Start
SaaS + Private Runner	Production deployments: managed platform, tasks execute inside your network	~1 hour	SaaS Installation
Self-Hosted	Air-gapped or fully on-premise requirements	4-8 hours	Self-Hosted Requirements

What Gets Deployed

Every installation deploys two lightweight components into your Kubernetes cluster via a single Helm chart (runwhen-local):

Component	What It Does
`workspace-builder`	Scans your cluster, discovers resources (namespaces, deployments, services, etc.), and matches them with relevant troubleshooting tasks from the task registry. Runs periodically to keep your workspace up to date.
`runner`	The control plane for task execution. Coordinates work from the platform, manages worker lifecycle, and reports results back. Stays inside your cluster — your credentials and raw data never leave your network.
`workers`	The pods that actually execute tasks. The runner deploys workers by combining a CodeCollection (a repository of task definitions) with the task runtime. Each CodeCollection gets its own pool of workers. Workers are the primary scaling lever — increase `workerReplicas` as the number of resources under management grows.

All components run in a dedicated runwhen-local namespace. For multi-cluster setups, deploy one instance of the Helm chart per cluster, all pointing to the same workspace.

Scaling

As your environment grows, background tasks (health checks, baseline monitoring) scale with the number of discovered resources. Workers handle this load. Increase workers per CodeCollection in values.yaml:

runner:
  codeCollections:
    - repoURL: https://github.com/runwhen-contrib/rw-cli-codecollection
      branch: main
      workerReplicas: 4   # increase for larger environments

A single worker can handle many tasks concurrently. Start with the default (4 replicas) and scale up if you notice task queue delays in larger clusters.

Prerequisites (All Paths)

Kubernetes cluster (v1.23+)
kubectl configured with cluster access
Helm 3.x installed
Cluster admin permissions (temporary, for initial RBAC setup)
Outbound HTTPS (port 443) to the endpoints listed below

Network & Registry Requirements

All RunWhen Local components communicate outbound only — no inbound ports need to be opened. The following URLs must be reachable from the cluster over HTTPS (port 443).

Platform & Service Endpoints

URL	Purpose	Used By
`papi.beta.runwhen.com`	Platform API calls	Runner, worker pods
`runner.beta.runwhen.com`	Runner control signals	Runner
`runner-cortex-tenant.beta.runwhen.com`	Metrics from workers and health-check pods	OpenTelemetry collector
`vault.beta.runwhen.com`	Secure secret storage and retrieval	Runner, worker pods
`storage.googleapis.com`	Execution log storage (via signed URL)	Worker pods

Container Registries

Registry	Images	Used By
`us-docker.pkg.dev`	Runner, robot-runtime base image (Google Artifact Registry)	Runner, worker pods
`us-west1-docker.pkg.dev`	CodeCollection images (built per-collection, per-branch)	Worker pods
`ghcr.io`	Workspace builder image (`runwhen-local`)	Workspace builder
`docker.io`	OpenTelemetry Collector image	OTel collector pod

CodeCollections & Discovery

Endpoint	Purpose	Used By
`github.com`	CodeCollection repositories (discovery and automatic configuration)	Workspace builder
`api.cloudquery.io`	Discovery plugin installation	Workspace builder
`runwhen-contrib.github.io`	Helm chart repository (only from the install machine)	Helm client

Additional access

If you are discovering cloud resources, the workspace builder and workers also need network access to the relevant Kubernetes, AWS, Azure, or GCP management APIs for any infrastructure included in discovery.

Proxy & private registries

If your cluster is behind a corporate proxy, the Helm chart supports proxy.httpProxy, proxy.httpsProxy, and proxy.noProxy settings. A custom proxy CA can be injected via proxyCA. Container image registries can be overridden with registryOverride for environments using private mirrors. See the values.yaml reference for details.

Helm Chart Reference

The runwhen-local Helm chart is maintained at github.com/runwhen-contrib/helm-charts.

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

Key configuration areas in values.yaml:

Section	Purpose
`workspaceName`	Must match the workspace name you created in the platform
`workspaceBuilder.workspaceInfo`	Discovery scope: namespaces, level of detail, cloud providers, CodeCollections
`workspaceBuilder.autoRun`	Discovery interval and upload behavior
`runner.codeCollections`	Which task libraries the runner should pull, and how many worker replicas to deploy per collection (default: `rw-cli-codecollection` with 4 workers)
`runner.runEnvironment.secretsProvided`	How secrets (kubeconfigs, cloud credentials) are mounted into task pods

See the full values.yaml for all options.