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

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

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.

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 below for format examples.

Then install the chart:

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.

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.

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

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

Single private repo (with token)

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

Multiple repos

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 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.

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) 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:

# 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:

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 →