Local install

Run the agent directly on your machine. No Kubernetes or Helm required. This is the fastest way to get started, and it's ideal for developing and testing locally before deploying to a cluster.

Prerequisites

You only need one thing: an API key with the agent and ops roles. See Authenticate the agent to set one up.

1. Download the agent

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

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

Once it finishes, you can run np-agent from your terminal.

2. Start the agent

Run the agent with your API key and a few required flags:

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

tip

np-agent also reads NP_API_KEY and NP_LOG_LEVEL from your environment if they're already set.

Here's what those flags do:

Flag	What it does
--api-key	Authenticates the agent with nullplatform
--runtime	Where the agent runs (host means directly on your machine)
--tags	Metadata tags for filtering. Format: key:value, comma-separated
--command-executor-env	Environment variables passed to the scripts the agent runs
--command-executor-debug	Enables detailed output for each command the agent executes
--webserver-enabled	Starts the agent's built-in web server

tip

See all available flags with np-agent --help.

Use AWS SSM for the API key

If you keep credentials in AWS SSM Parameter Store, the agent can read its API key from there instead of taking it as a CLI flag. This keeps the key out of your shell history and out of local files.

You need:

• An SSM parameter of type SecureString holding the API key (e.g. /nullplatform/agent/api-key).
• AWS credentials available to your shell (aws configure or an active AWS_PROFILE) with ssm:GetParameter and kms:Decrypt on the parameter.

Then replace --api-key=$NP_API_KEY with --ssm-apikey-parameter:

np-agent \
  --ssm-apikey-parameter=/nullplatform/agent/api-key \
  --runtime=host \
  --tags=key:value \
  --webserver-enabled

The agent fetches the parameter at startup with decryption enabled and retries up to 5 times on transient errors.

Optional flags

Log verbosity controls how much detail the agent prints:

--log-level=INFO

Options: ERROR, WARNING, INFO (default), DEBUG

Pretty-print logs makes output easier to read (colorized, nicely formatted JSON):

--log-pretty-print

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

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 →