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 roles: ops and secops.
  4. 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. Set 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="env:dev,team:secops"
export AGENT_REPO=<https://git-provider/your-org/your-repo.git#your_branch>
Click to view variable details and examples

NP_API_KEY​

Your API key, created in step 1. 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. Format them as comma-separated key:value pairs.

export AGENT_TAGS="env:dev,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.

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

4. 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
More configuration options

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. (Optional) Set log verbosity​

The agent can produce different levels of log detail to help with troubleshooting or monitoring.

You can choose from:

  • ERROR – Only show errors
  • WARNING – Show warnings and errors
  • INFO – Show key operational messages (default)
  • DEBUG – Show detailed debug info (most verbose)

Example:

export NP_LOG_LEVEL=INFO

3. Run the agent​

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

np-agent \
  --apikey=$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.

💡 TIP: See all available flags with:

np-agent --help

Want to implement agent-baked scopes?​

See the how-to guides for agent-backed scopes to set up and run prebuilt environments.