---
sidebar_label: Install with Helm
toc_max_heading_level: 3
doc_id: c7a9f4e2-1b3d-4a85-9c6f-e7d8b2a13045
description: >-
  Step-by-step guide to installing the nullplatform agent on a Kubernetes cluster using Helm.
keywords:
  - helm
  - kubernetes
  - agent installation
  - nullplatform agent
  - np-agent
---

# Install with Helm

Use this method to run the agent on a Kubernetes cluster. It's the recommended approach for production environments and CI/CD pipelines.

## Prerequisites

- A Kubernetes cluster
- Helm 3+
- An API key with the **agent** and **ops** roles. See [Authenticate the agent](authentication.md)

:::info
All examples in this guide use the `nullplatform-tools` namespace. The `helm install` commands include `--create-namespace`, so Helm creates it on first install. If you use a different namespace, adjust `--namespace` and any `kubectl -n` flags accordingly.
:::

## 1. Add the Helm repository

```bash
helm repo add nullplatform https://nullplatform.github.io/helm-charts
helm repo update
```

## 2. Set your values and install

The minimum you need is an API key, an agent repo, and tags.

```bash
export NP_API_KEY=<your_api_key>
export AGENT_TAGS=<key1:value1,key2:value2>
export AGENT_REPO=<https://git-provider/your-org/your-repo.git#your_branch>
```

> 💡 **Tip:** Check the logs to confirm that your `AGENT_REPO` was cloned correctly. See the [Variables section](#variables) below for format examples.

Then install the chart:

```bash
helm install nullplatform-agent nullplatform/nullplatform-agent \
  --namespace nullplatform-tools --create-namespace \
  --set configuration.values.NP_API_KEY=$NP_API_KEY \
  --set configuration.values.AGENT_REPO=$AGENT_REPO \
  --set configuration.values.TAGS="$AGENT_TAGS"
```

:::info
For more advanced installs, see the [nullplatform Helm charts repo](https://github.com/nullplatform/helm-charts).
:::

## Verify installation

1. In the platform UI, go to **Platform settings > Agents**.
2. Filter by tags or agent ID to find your new agent.

If it shows up, you're good to go.

## Variables

Quick reference for the values you pass to the chart. For full details, see the [nullplatform Helm charts repo](https://github.com/nullplatform/helm-charts/tree/main/charts/agent).

### Required

| Value | What it does | Helm path | Example |
| --- | --- | --- | --- |
| API key | Authenticates the agent | `configuration.values.NP_API_KEY` | `NP_API_KEY="npk_..."` |
| Agent repo | Where the agent reads scopes and actions from | `configuration.values.AGENT_REPO` | `AGENT_REPO="https://git-provider/org/repo.git#main"` |
| Tags | Metadata for filtering in the UI | `configuration.values.TAGS` | `TAGS="environment:dev,team:platform"` |

### Optional

| Value | What it does | Helm path | Example |
| --- | --- | --- | --- |
| Log level | Controls verbosity | `configuration.values.NP_LOG_LEVEL` | `NP_LOG_LEVEL="INFO"` |

### AGENT_REPO formats

You can pass one repo or several, separated by commas. Add `#branch` to target a specific branch.

**Single public repo**

```bash
AGENT_REPO="https://git-provider/your-org/your-repo.git#your_branch"
```

**Single private repo (with token)**

```bash
AGENT_REPO="https://<git-token>@git-provider.com/your-org/private-repo.git#your_branch"
```

**Multiple repos**

```bash
AGENT_REPO="https://git-provider/your-org/your-repo.git#your_branch,https://<git-token>@git-provider.com/your-org/private-repo.git#your_branch"
```

:::tip
For private GitHub repos in production, prefer a [GitHub App](install-helm-github-app.md) over embedding a personal access token in the URL. The chart includes an init container that handles the App-based clone for you.
:::

:::info
For the full list of values and defaults, check the [nullplatform Helm charts repo](https://github.com/nullplatform/helm-charts).
:::

## Use AWS SSM for the API key

For EKS installs, you can keep the API key in AWS SSM Parameter Store instead of passing it as a Helm value. The agent supports `--ssm-apikey-parameter` as an alternative to `--apikey` and fetches the parameter at startup with decryption enabled.

You need:

- An SSM parameter of type `SecureString` holding the API key (e.g. `/nullplatform/agent/api-key`).
- An IAM role for the agent's service account ([IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)) with `ssm:GetParameter` and `kms:Decrypt` on that parameter.

Then override the chart `args` to use the SSM flag, leave `NP_API_KEY` empty, and annotate the service account with the IRSA role:

```yaml
# values.yaml
serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/nullplatform-agent-irsa

configuration:
  values:
    NP_API_KEY: ""
    AGENT_REPO: "https://git-provider/your-org/your-repo.git#main"
    TAGS: "environment:prod,team:platform"

args:
  - --tags=$(TAGS)
  - --ssm-apikey-parameter=/nullplatform/agent/api-key
  - --runtime=host
  - --command-executor-debug
  - --webserver-enabled
  - --command-executor-git-command-repos
  - $(AGENT_REPO)
```

Install with:

```bash
helm install nullplatform-agent nullplatform/nullplatform-agent \
  --namespace nullplatform-tools --create-namespace \
  -f values.yaml
```

## Next step: create a notification channel

The agent is now installed and registered. Without a notification channel, it won't respond to any platform events.

[Create a notification channel →](agent-channel.md)