Skip to main content

Install the agent

The recommended way to install the nullplatform agent is via Helm. This method gives you full control over authentication, tags, and GitHub integration—and fits well into CI/CD workflows.

If you're just trying things out, you can also run our quick-install script.

Installation methods​

Prerequisites​

Before you begin, make sure you have:

  • A Kubernetes cluster
  • Helm 3+ (if you're installing with Helm)
  • An API key

To create an API key in the nullplatform UI:

  1. Go to Platform settings > API keys and click + New API key.
  2. Select the account resource where the API key’s roles will be assigned.

    ⚠️ Important: Roles must be assigned at the account level—otherwise the setup won’t work.

  3. Assign the following roles:
Roles needed for agent api key
  1. Save your API key somewhere safe—you’ll need it during installation.

Helm installation​

1. Add the Helm repository​

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

2. Install the chart​

Use the following command to install the agent with your configuration:

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

Environment variables​

These environment variables configure the agent’s API key, tags, and scope source.

export NP_API_KEY=<your_api_key>
export AGENT_TAGS=<value:key>
export AGENT_REPO=<https://git-provider/your-org/your-repo.git#your_branch>

📖 See the Variables reference section below for more information and examples.

Verify installation​

Let’s make sure everything is working properly.

Check the agent in the UI

  1. Grab the agent ID from the install logs. It looks like this: "id\":\"123b245d-6e7b-4c56-d78e-12f34b50\"
  2. In the platform UI, go to Platform settings > Agents.
  3. You should see your new agent listed by that ID.

Quick install​

If you just want to get the agent up and running without configuring Helm, you can use our 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 will download 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 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 \

Here’s what those flags do:

  • --apikey: 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 (useful for filtering in the UI).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 – SExtra-detailed debug info

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

    --log-pretty-print

Variables (reference & examples)​

This section lists the environment variables used in this guide, with concise descriptions and examples.

NP_API_KEY​

Your API key. This authenticates the agent with the platform.

AGENT_TAGS​

Used to assign metadata tags to the agent. Tags help with filtering and identifying agents in the UI.

Just follow this format: "your_key1:your_value1".

export AGENT_TAGS="environment:development"

💡 You can also add more tags, separated by commas: "environment:development,team:secops".

AGENT_REPO​

Specifies the Git repository or repositories the agent should read from. The format you use depends on whether you're referencing a single repository, a private repository with a token, or multiple repositories.

Format examples:

  • Single public repository

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

    Example:

    export AGENT_REPO="https://github.com/nullplatform/public-repo.git#main"

  • Single private repository (requires token)

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

    Example:

    export AGENT_REPO="https://gh_a1B2c3D4e5F6g7H8i9J0kLmNopQRstUVwxYZ@github.com/nullplatform/private-repo.git#main"

  • Multiple repositories (comma-separated)

    If you need to point the agent to more than one repository, separate each URL with a comma (no spaces).

    export 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"