Install the agent

We recommend installing the nullplatform agent via Helm. It’s the best fit for production clusters and CI/CD automation.

If you’re just testing locally, you can also run the agent directly with the np-agent binary.

Choose your installation method

• Install via Helm. (Recommended for production and automation)
• Use the CLI script to install in one step for serverless instances or testing.

Prerequisites

Before you start, make sure you have:

• A Kubernetes cluster
• Helm 3+ (if you’re installing with Helm)
• An API key with the agent and ops roles. See Authenticate the agent

Install with Helm

The following instructions rely on the nullplatform Helm charts repo.

1. Add the Helm repository

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

2. Set your agent values and install

The minimum values you’ll need to install is an API key, the 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 reference section below for more information and examples.

Then run helm install command with those values:

helm install nullplatform-agent nullplatform/nullplatform-agent \
  --set configuration.values.NP_API_KEY=$NP_API_KEY \
  --set configuration.values.AGENT_REPO=$AGENT_REPO \
  --set configuration.values.TAGS="$AGENT_TAGS"

For more advanced installs, see the nullplatform Helm charts repo.

Quick install with the np-agent script

Use this for local testing or troubleshooting. For Kubernetes and production installs, use Helm.

If you just want to get the agent up and running without configuring Helm, you can use the quick-install script. This method downloads the np-agent binary and lets you run it directly from your terminal.

1. Download and install the agent

This downloads the latest np-agent binary to your local system (usually to ~/.local/bin/np-agent).

curl https://cli.nullplatform.com/agent/install.sh | bash

Once complete, you’ll be able to call np-agent from your terminal.

2. Run the agent

Start the agent by passing in your API key, tags, and any additional parameters:

np-agent \
  --api-key=$NP_API_KEY \
  --runtime=host \
  --tags=key:value \
  --command-executor-env=NP_API_KEY="\"$NP_API_KEY\"" \
  --command-executor-debug \
  --webserver-enabled

Note: np-agent also reads NP_API_KEY and NP_LOG_LEVEL from your environment if they’re set.

Here’s a quick rundown of those flags:

• --api-key: Authenticates the agent with nullplatform (your API key from the prerequisites).
• --runtime: Specifies where the agent runs (host means directly on your system).
• --tags: Adds metadata tags to the agent. Format them as comma-separated key:value pairs.
• --command-executor-env: Passes environment variables to executed commands.
• --command-executor-debug: Enables debug output for command execution.
• --webserver-enabled: Starts the agent’s built-in webserver.

See all available flags with:

np-agent --help

Optional flags (recommended)

• Log verbosity: Choose how much detail the agent prints. Helpful for troubleshooting.

  --log-level=INFO

  You can choose from:

  • ERROR – Only errors
  • WARNING – Warnings and errors
  • INFO – General run info (default)
  • DEBUG – Extra-detailed debug info

• Pretty-print logs: Makes console output easier to read: colorized and nicely formatted JSON.

  --log-pretty-print

Verify installation

Let’s make sure everything is working properly.

Check the agent in the UI

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

You should see your new agent listed by that ID.

Variables (reference & examples)

This section is a quick lookup for the values you pass to the agent chart. For more details, see the nullplatform Helm charts repo.

Using np-agent directly?

You’ll pass the same data as flags instead of Helm values. np-agent also reads NP_API_KEY and NP_LOG_LEVEL from your environment if they’re set.

• NP_API_KEY → --api-key
• AGENT_REPO → --command-executor-git-command-repos
• TAGS → --tags
• NP_LOG_LEVEL → --log-level

Required values

These are the minimum values you need to install the chart.

Value	What it does	Helm path	Example
API key	Authenticates the agent with nullplatform	configuration.values.NP_API_KEY	NP_API_KEY="npk_..."
Agent repo	Tells the agent where to read scopes and actions	configuration.values.AGENT_REPO	AGENT_REPO="https://git-provider/org/repo.git#main"
Tags	Adds metadata for filtering in the UI	configuration.values.TAGS	TAGS="environment:dev,team:platform"

Optional values

Use these when you want to organize or tune the agent.

Value	What it does	Helm path	Example
Log level	Changes verbosity	configuration.values.NP_LOG_LEVEL	NP_LOG_LEVEL="INFO"

AGENT_REPO formats

The agent repo can be a single repo or a comma-separated list. Use the #branch suffix to select a branch.

Single public repository

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

Single private repository (with token)

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

Multiple repositories (comma-separated, no spaces)

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"

info

For the full list of values and defaults, check the nullplatform Helm charts repo.

Next steps

Installing the agent only registers it. To trigger actions, create an agent notification channel after install. See Notification channels.