---
sidebar_label: Agent
toc_max_heading_level: 2
doc_id: 25f409ee-fea4-4f84-94d7-774afa7901b2
description: >-
  Lightweight service connecting your environment to nullplatform API for
  automation, monitoring, and event handling securely.
keywords:
  - nullplatform agent
  - automation
  - kubernetes
  - API integration
  - monitoring
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# The nullplatform agent

The **nullplatform agent** is a lightweight service you can run anywhere, from your laptop to a Kubernetes cluster. It connects your environment securely to the nullplatform API, so you can automate tasks, monitor scopes and services, trigger actions, and handle event-based notifications without exposing your infrastructure.

> ℹ️ This setup is privacy-first: **your data stays in your cluster**.
> Only minimal metadata and telemetry are sent to nullplatform.

## Required setup path

Follow this order so the agent can actually execute work:

1. **Create an API key** with the Agent and Ops role.
2. **Install the agent** and pass the API key as `NP_API_KEY`.
3. **Create an agent notification channel** that targets this agent.

## How it works

The agent is a small binary that can run in many ways, on your local machine, in a container, or on a Kubernetes
cluster (via Helm, Docker, or just the binary). Here's what it does:


- Authenticates with the nullplatform API using your API key  
- Registers itself with optional tags (e.g. `environment:dev`, `team:secops`)  
- Polls the API for matching tasks, scopes, or triggers  
- Runs matching commands or workflows inside your environment  
- Optionally sends logs, telemetry, and results back to nullplatform  

> 🔒 The agent is **outbound-only**. It only needs to be able to connect to `agents.nullplatform.com` on port `443`.


### Minimal flow

```mermaid
sequenceDiagram
  autonumber
  participant You as You
  participant Agent as nullplatform agent
  participant API as nullplatform API

  You->>Agent: Install with API key and tags
  Agent->>API: Register and poll for work
  API-->>Agent: Send action
  Agent->>Agent: Run local script / command
  Agent->>API: Return output and logs
```

## Key features at a glance

| Feature                        | Description                                                                                                                         |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Tag-based routing**          | Agents only respond to tasks that match their tags                                                                                  |
| **Secure API integration**     | Use API keys with fine-grained access                                                                                               |
| **Notification channels**      | Run local scripts in response to platform events, using a git-audited flow                                                          |
| **Flexible runtime options**   | Deploy the agent using Helm (K8s), Docker, binary, or serverless (e.g. Lambda)                                                      |
| **Observability**              | Capture logs, exit codes, and outputs from workflows inside your infra. (Note: the agent itself doesn’t expose internal monitoring) |
| **Multiple deployment models** | Use in local dev (e.g. Minikube), cloud environments (e.g. EKS, GKE), or CI/CD pipelines                                            |

<!-- ## What the agent unlocks

Once the agent is installed, it becomes the link between nullplatform and your infrastructure. Here’s what it lets you do:


- **Control your scopes directly in your environment**  
  Launch tasks like security scans or provisioning workflows directly inside your infra.

- **Connect platform events to your systems**  
  Trigger commands in containers, virtual machines, or other systems when something happens on the platform.

- **Use custom actions without extra glue code**  
  Respond to events (like deployments or job completions) with local scripts—no brittle webhooks required.

- **Manage internal services**  
  Link the platform to services or APIs running inside your infrastructure.

- **Send back telemetry and task results**  
  Capture logs, outputs, and task status from your local runs and send them to the platform UI.

- **Keep sensitive data local**  
  Everything runs on-prem. No data leaves your infra unless you choose to share logs or outputs. -->

## What’s next

Explore the following pages to learn more:

- [**Security model**](./security): Understand what nullplatform guarantees and what you control  
- [**Authentication**](./authentication): Configure API keys with NRN-scoped permissions for agents  
- [**Installation**](./installation): Install the agent with Helm and verify it's working  
- [**Notification channels**](./agent-channel): Let platform events trigger your local scripts