---
title: "Install the standard Kubernetes operator | Speedscale Docs"
description: "Install and verify the Speedscale Kubernetes operator with Helm, speedctl, Argo CD, or rendered manifests."
canonical: "https://docs.speedscale.com/getting-started/installation/install/kubernetes-operator/"
---

[Documentation index](https://docs.speedscale.com/getting-started/llms.txt) | [Markdown](https://docs.speedscale.com/getting-started/installation/install/kubernetes-operator/index.md) | [Canonical page](https://docs.speedscale.com/getting-started/installation/install/kubernetes-operator/)

# Install the standard Kubernetes operator

The Speedscale operator runs in your cluster and manages the components used to capture and replay traffic. This installation creates cluster-scoped RBAC, a Speedscale CRD, and admission webhooks. If your installer can write only in one existing namespace, use the [namespace-scoped installation](https://docs.speedscale.com/getting-started/installation/install/kubernetes-namespaced/). See [Kubernetes installation options](https://docs.speedscale.com/getting-started/installation/install/kubernetes/) to compare both modes.

<a id="prerequisites"></a>

## Prerequisites

*   A Kubernetes cluster and `kubectl` access with permission to install cluster-scoped resources.
*   A service account API key from [Tenant Settings](https://app.speedscale.com/tenant). Ask a tenant administrator to create one if needed.
*   [Helm 3](https://helm.sh/docs/intro/install/) for the Helm and rendered-manifest methods, or [speedctl](https://docs.speedscale.com/getting-started/installation/install/cli/) for the CLI method.
*   The network access described in [Evaluation prerequisites](https://docs.speedscale.com/getting-started/evaluation/).

Check [platform requirements](https://docs.speedscale.com/getting-started/installation/install/kubernetes/#check-your-platform-requirements) before installing on OpenShift, GKE Autopilot, EKS Auto Mode, or a cluster running Istio. The Helm and manifest examples below enable eBPF capture; confirm the [eBPF system requirements](https://docs.speedscale.com/reference/ebpf-traffic-collection/#system-requirements) first. Use the platform-specific values where required.

<a id="install-with-ai-agent"></a>

## Install with your coding agent

This platform install deliberately installs **both speedctl and proxymock**. For proxymock alone without cluster setup, use the [proxymock-only agent install](https://docs.speedscale.com/proxymock/getting-started/installation/#install-with-ai-agent).

Let your coding agent (Claude Code, Cursor, Codex, Gemini CLI, Kiro, or any assistant that can read a URL and run commands) do the whole install. Paste this into the chat:

```text
Install Speedscale for me. First fetch the agent skill at
https://raw.githubusercontent.com/speedscale/skills/main/skills/install-speedscale/SKILL.md
and the references/ and scripts/ files it links to (same base URL), save them
under your skills directory, then follow the skill. Ask me before touching a
Kubernetes cluster.
```

The [install-speedscale skill](https://github.com/speedscale/skills) follows the same steps as the manual install below. It installs `speedctl` and `proxymock`, adds Helm and kubectl if they are missing, sets up your API key without ever printing it, and picks Helm values for your platform (EKS, GKE, AKS, minikube, kind, OpenShift). Then it verifies the operator and, only for the agent you select, offers to add the proxymock MCP server and bundled skills after previewing the paths. The agent announces every step that changes something before running it. It stops for you at browser sign-in and before touching a cluster whose name looks like production. With no cluster available, it installs just the CLIs.

Already have proxymock? `proxymock mcp install --client claude-code --skills` offers MCP and bundled skills for that selected client, preferring project scope. Add `--dry-run` to preview paths. You can also add it as a Claude Code plugin with `/plugin marketplace add speedscale/skills`, or add it to other agents with `npx skills add speedscale/skills`.

See [Agent skills](https://docs.speedscale.com/proxymock/agent-skills/) for the other skills.

<a id="retrieve-your-api-key"></a>

## Retrieve your API key

For manual installation, use a service account API key so the cluster's access is independent of an employee's account. With the Helm, Argo CD, and rendered-manifest methods, create the namespace and load the key from a protected file into a Secret. Write the file without a trailing newline, for example `printf %s "$KEY" > /secure/path/to/key`; a newline becomes part of the key and authentication fails:

```bash
kubectl create namespace speedscale
kubectl -n speedscale create secret generic speedscale-apikey \
  --from-file=SPEEDSCALE_API_KEY=/secure/path/to/key \
  --from-literal=SPEEDSCALE_APP_URL=app.speedscale.com
```

If the namespace or Secret already exists, use your platform's provisioning process to manage it. For `speedctl install`, supply the service account key when prompted by the wizard.

<a id="install-method"></a>

## Choose an installation method

For Helm and rendered manifests, add the public chart repository:

```bash
helm repo add speedscale https://speedscale.github.io/operator-helm/
helm repo update
```

Create `speedscale-values.yaml` with your cluster name and any required platform settings. The key itself stays in the Secret:

```yaml
apiKeySecret: speedscale-apikey
clusterName: YOUR-CLUSTER-NAME
ebpf:
  enabled: true
```

Use `ebpf.enabled: false` if your cluster cannot run eBPF and follow the [sidecar fallback](https://docs.speedscale.com/getting-started/installation/sidecar/install/). Review the chart's [install and upgrade lifecycle](https://docs.speedscale.com/reference/helm/#install-and-upgrade-lifecycle) for resource ownership, hooks, and CRD handling.

**Helm**

Install with the values file:

```bash
helm install speedscale-operator speedscale/speedscale-operator \
  --namespace speedscale \
  --values speedscale-values.yaml
```

Keep this values file for upgrades. See the [Helm values reference](https://docs.speedscale.com/reference/helm/) for additional configuration.

**speedctl**

[Install speedctl](https://docs.speedscale.com/getting-started/installation/install/cli/), then run:

```bash
speedctl install
```

Choose **Kubernetes** and follow the prompts. This wizard is available on macOS, Linux, and Windows. After installation, follow [Enable eBPF capture](https://docs.speedscale.com/reference/ebpf-traffic-collection/#installation), or use the [sidecar fallback](https://docs.speedscale.com/getting-started/installation/sidecar/install/) if your cluster cannot run eBPF.

<a id="optional-adding-image-pull-secrets"></a>

### Image pull secrets

If your images require existing image pull Secrets, pass their names to the wizard:

```bash
speedctl install --imgpullsecrets my-secret1,my-secret2
```

**Argo CD**

Create the API key Secret in the destination cluster before syncing the application. If Argo CD creates the namespace, add `CreateNamespace=true` to `syncPolicy.syncOptions`, and make sure the Secret (for example a SealedSecret or ExternalSecret) syncs before this Application, such as in an earlier sync wave, because the operator needs it at startup. Apply the same cluster name and platform values to `source.helm.values`. Set `targetRevision` to the chart version you reviewed in the [Helm repository](https://github.com/speedscale/operator-helm/blob/main/README.md).

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: speedscale-operator
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://speedscale.github.io/operator-helm/
    targetRevision: YOUR-CHART-VERSION
    chart: speedscale-operator
    helm:
      values: |-
        apiKeySecret: speedscale-apikey
        clusterName: YOUR-CLUSTER-NAME
        ebpf:
          enabled: true
  destination:
    namespace: speedscale
    name: in-cluster
  syncPolicy:
    automated: {}
```

Review [rendered manifests and GitOps](https://docs.speedscale.com/reference/helm/#rendered-manifests-and-gitops) before enabling automated sync. Argo CD handles chart hooks and CRDs differently from a Helm CLI installation.

**Rendered manifests**

Helm runs on your workstation; it does not need to run in the cluster. Render the chart to Kubernetes YAML using your values file:

```bash
helm template speedscale-operator speedscale/speedscale-operator \
  --namespace speedscale \
  --values speedscale-values.yaml > speedscale-operator.yaml
```

Manage the output through your GitOps process or use it as a Kustomize resource:

kustomization.yaml

```yaml
resources:
  - speedscale-operator.yaml
```

Hook ordering

Applying rendered YAML does not reproduce Helm's hook ordering. Review [rendered manifests and GitOps](https://docs.speedscale.com/reference/helm/#rendered-manifests-and-gitops) before applying the output or enabling automated sync.

Re-render when upgrading so chart changes and image versions stay current. The output can contain generated TLS private keys; handle it according to your secret-management policy. If your organization prohibits Helm tooling entirely, [contact Speedscale Support](mailto:support@speedscale.com) for help producing custom manifests.

<a id="verify-installation"></a>

## Verify installation

Check that the operator and forwarder pods are running:

```bash
kubectl -n speedscale get pods
```

Expect at least the operator and forwarder pods in `Running` state; the suffixes differ on your cluster:

```text
NAME                                    READY   STATUS    RESTARTS   AGE
speedscale-forwarder-xxxxxxxxxx-xxxxx   1/1     Running   0          5s
speedscale-operator-xxxxxxxxxx-xxxxx    1/1     Running   0          15s
```

When eBPF is enabled, also check the collector pods:

```bash
kubectl -n speedscale get pods -l app=speedscale-nettap
```

If proxymock is installed, check component readiness, connectivity, and your kubeconfig permissions:

```bash
proxymock cluster status --speedscale-namespace speedscale
```

For failures, see [installation troubleshooting](https://docs.speedscale.com/getting-started/installation/install/troubleshooting/) or ask in the [Speedscale Community](https://slack.speedscale.com/).

<a id="kerberos-cloud-proxy"></a>

## Kerberos cloud proxy

If your outbound proxy requires Kerberos, follow [Kerberos proxy authentication](https://docs.speedscale.com/reference/proxy_config/#kubernetes-operator-setup) to configure the operator override and mount credentials. The operator propagates these settings to forwarder and inspector.

<a id="private-registry-images"></a>

## Private registry images

If your organization requires approved Redis or Java runtime images, configure `replayComponents.redis.image` and `jks.image` in your Helm values. The [Helm values reference](https://docs.speedscale.com/reference/helm/#bring-your-own-redis-and-java-runtime-images) covers runtime requirements and truststore behavior, with a [private registry example](https://docs.speedscale.com/reference/helm/#private-registry-example) for Artifactory.

<a id="next-steps"></a>

## Next steps

Use the [tutorial](https://docs.speedscale.com/getting-started/tutorial/) to record and replay a demo application, or follow [cluster capture and replay with proxymock](https://docs.speedscale.com/proxymock/guides/cluster/). See [eBPF capture targets](https://docs.speedscale.com/reference/ebpf-traffic-collection/#enabling-via-helm) to select workloads for capture.