Getting Started

Install the Remediator Agent and run your first policy violation remediation.

Prerequisites

Required Components

Kubernetes cluster running Kubernetes 1.20+
Helm 3.x installed and configured
kubectl configured to access your cluster
Kyverno installed and running with policy reports enabled
ArgoCD or FluxCD (optional) — required for the argoHub / fluxHub multi-cluster modes

Required Credentials

Nirmata Control Hub Service Account Token — create a Service Account in Nirmata Control Hub and copy its secret

This token is required for the default configuration, which uses Nirmata AI as the LLM provider and the Nirmata GitHub App for Git access. If you supply both your own LLM provider (AWS Bedrock, Azure OpenAI, or the Anthropic API) and your own Git credentials (a PAT or your own GitHub App), you can install with nirmata.auth=none and skip this step entirely — see Nirmata Platform Authentication for what that turns off.

Create a Service Account

Log in to Nirmata Control Hub
Navigate to Identity & Access from the left sidebar
Go to Service Accounts and create a new one
Copy the generated secret — you’ll use it in the next step

Installation

1. Create Namespace and Secrets

kubectl create namespace nirmata

kubectl create secret generic nirmata-service-account-token \
  --from-literal=service-account-token=YOUR_NCH_SERVICE_ACCOUNT_TOKEN \
  --namespace nirmata

2. Add the Helm Repository

helm repo add nirmata https://nirmata.github.io/kyverno-charts
helm repo update nirmata

3. Install the Agent

helm install nirmata-agent nirmata/nirmata-agent --devel \
  --namespace nirmata \
  --create-namespace
```json




Note

    The chart uses serviceAccountToken authentication by default and expects the nirmata-service-account-token secret created above. To use API token authentication instead, set:
--set nirmata.auth="apiToken" \
--set nirmata.apiTokenSecret="nirmata-api-token"
To run with no Nirmata platform credential at all, set --set nirmata.auth="none" and configure your own LLM provider and Git credentials.Configuring through Helm values
This guide creates the three custom resources by hand so each one is visible. The chart can also create them from values: llm.* renders the LLMConfig and tool.* renders the ToolConfig (both enabled by default), and remediator.enabled=true renders the Remediator. remediator.enabled defaults to false, so the install above deploys the controller without a Remediator until you create one.### 4. Verify the Installation
```bash
# Check pods are running
kubectl get pods -n nirmata -l app.kubernetes.io/name=nirmata-agent
# Check custom resource definitions were installed
kubectl get llmconfigs,toolconfigs,remediators -n nirmata
# Tail the agent logs
kubectl logs -n nirmata -l app.kubernetes.io/name=nirmata-agent --tail=50
```yaml
---
## Quick Configuration
The agent requires three custom resources before it will start remediating. See [Configuration](../configuration/) for full details and all available options.
### 1. ToolConfig (Git credentials)
**GitHub Personal Access Token:**
```bash
kubectl create secret generic github-pat-token \
 --from-literal=token=GITHUB_PAT_TOKEN \
 --namespace nirmata
kubectl apply -f - <<EOF
apiVersion: serviceagents.nirmata.io/v1alpha1
kind: ToolConfig
metadata:
name: toolconfig-sample
namespace: nirmata
spec:
type: github
credentials:
method: pat
pat:
tokenSecretRef:
name: github-pat-token
namespace: nirmata
key: token
defaults:
git:
pullRequests:
branchPrefix: "remediation-"
titleTemplate: "[Auto-Remediation] Fix policy violations: "
commitMessageTemplate: "Auto-fix: Remediate policy violations: "
customLabels:
- "auto-remediation"
systemLabels:
- "clusterName"
- "namespace"
EOF

Prefer using the Nirmata GitHub App over a personal access token — it avoids managing secrets manually and provides automatic token rotation.

2. LLMConfig (AI provider)

The Helm chart creates a default LLMConfig using Nirmata AI automatically. If you need to create it manually:

kubectl apply -f - <<EOF
apiVersion: serviceagents.nirmata.io/v1alpha1
kind: LLMConfig
metadata:
  name: nirmata-agent-llm
  namespace: nirmata
spec:
  type: nirmataAI
  nirmataAI:
    model: ""
EOF

3. Remediator

Local Mode (scans the cluster where the agent is installed):

# Create a ConfigMap mapping Git repos to namespaces
kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: repo-namespace-mapping
  namespace: nirmata
data:
  mapping: |
    [
      {
        "repo": "https://github.com/your-org/your-repo",
        "branch": "main",
        "path": "k8s/",
        "targetNamespace": "default"
      }
    ]
EOF

# Create the Remediator
kubectl apply -f - <<EOF
apiVersion: serviceagents.nirmata.io/v1alpha1
kind: Remediator
metadata:
  name: remediator-local
  namespace: nirmata
spec:
  environment:
    type: localCluster
  target:
    localCluster:
      repoNamespaceMappingRef:
        name: repo-namespace-mapping
        namespace: nirmata
        key: mapping
  remediation:
    triggers:
      - schedule:
          crontab: "0 */6 * * *"
    llmConfigRef:
      name: nirmata-agent-llm
      namespace: nirmata
    gitCredentials:
      name: toolconfig-sample
      namespace: nirmata
    eventPolling:
      enabled: true
      intervalMinutes: 5
    actions:
      - type: CreatePR
        toolRef:
          name: toolconfig-sample
          namespace: nirmata
EOF
```yaml

---

## Uninstalling

```bash
helm uninstall nirmata-agent -n nirmata

Secrets you created manually are not removed — clean those up separately if needed.