---
sidebar_label: Local install
toc_max_heading_level: 3
doc_id: b8d3c712-5f4e-4096-a7b1-3e6f2d894c51
description: >-
  Run the nullplatform agent locally on your machine without Kubernetes, for development and testing.
keywords:
  - local install
  - np-agent
  - binary
  - development
  - testing
  - nullplatform agent
---

# 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](authentication.md) to set one up.

## 1. Download the agent

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

```bash
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:

```bash
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`:

```bash
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:

```bash
--log-level=INFO
```

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

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

```bash
--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 →](agent-channel.md)