# EvoHub Agent overview

The EvoHub agent is software your organization runs in its own infrastructure. It lists what is running there, read-only, and reports it to [EvoHub Catalog](https://docs.evohub.io/catalog-overview.md). It runs in two places:

- **In a Kubernetes cluster**, installed with Helm. It describes the cluster's workloads, services and how they connect. See [Install on Kubernetes](https://docs.evohub.io/agent-kubernetes.md).
- **On a Linux VM**, installed under systemd. It describes that machine: its services, containers and listening ports. See [Install on a VM](https://docs.evohub.io/agent-vm.md).

Secret values and environment variable values are removed inside your network, before anything is sent. What the agent reads, sends and never sends is in [What the agent sends](https://docs.evohub.io/agent-data-and-redaction.md).

## Enrollment

An agent joins your organization with an **enrollment token**:

:::steps
### Create the token
In the console, open **Organization → Agents** and select **New agent**. Give it a **Name**, choose **Where it runs** (**Kubernetes cluster** or **Linux VM**) and the **Environment** it reports to, then select **Create token**.

### Install the agent with it
The console shows the install commands with the token filled in. The token works **once** and is valid for **15 minutes**. If it expires, create another.

### The agent enrolls
On first start the agent generates its own key pair, saves the private key where it runs, and sends EvoHub its public key with the token. Once enrolled, the token is spent and never sent again.
:::

Each agent reports to exactly one environment, the one chosen when its token was created. The environment never travels in the agent's requests, so an agent cannot report into an environment it was not enrolled for.

## Signed requests

The agent holds no password and no API key. Every request after enrollment is signed with the agent's private key, which never leaves your cluster or VM. The signature covers:

- the agent's ID
- the method, the path and the query
- the SHA-256 of the body
- a timestamp
- a random nonce

EvoHub refuses a nonce it has already seen and a timestamp more than five minutes off, so a request copied in transit cannot be replayed. Nothing the agent sends after enrollment can be reused by someone who sees it.

An agent can only send inventory about its own environment. It cannot read anything from EvoHub, and nothing else can send inventory: there is no permission or API key that can.

## Network

- **Outbound:** HTTPS on TCP 443 to `api.evohub.io`; in Kubernetes, your cluster's API server; and DNS.
- **Inbound:** none. The agent listens on no port.
- **Proxies:** the agent honours `HTTPS_PROXY` and `NO_PROXY`. It trusts the public CA roots only, so a proxy that re-signs TLS with a private CA is not supported. A proxy that terminates TLS can read what the agent sends, including the enrollment token while it enrolls.
- **Redirects** are never followed. A redirect is logged as an error.

## How often it reports

| Report | Default |
| --- | --- |
| Heartbeat | Every minute |
| Full sweep of everything it can list | Every 5 minutes |
| Live state: how each workload or service is running now | Every minute |

When a sweep could not list something, it says so, and EvoHub marks nothing missing from that sweep. If an agent stops sending heartbeats for ten minutes, what it reported is shown as stale rather than missing.

## Managing agents

**Organization → Agents** lists every agent with where it runs, what it is used for, when it was last seen, and whether it is **Reporting**, **Not reporting** or **Revoked**. The agent's version, which it reports on every heartbeat, is kept too.

- **Rename agent** changes how it is shown. The agent itself keeps running as it is.
- **Revoke agent** stops EvoHub accepting anything from it. Uninstalling an agent does not revoke it; revoke it as well.
- To pause an agent's reports without revoking it, pause its source under **Catalog → Environments and agents**.

Seeing agents needs `identity:agent:read`; creating tokens, renaming and revoking need `identity:agent:write`, and enrolling also needs `catalog:source:write`. By default Owners and Admins can enroll agents. See [Catalog permissions](https://docs.evohub.io/catalog-permissions.md).

## When EvoHub refuses the agent

When EvoHub refuses a request, the agent's log entry carries an `action` field saying what to do, for example `upgrade it`, `resume it there` or `fix its time synchronisation`. After a refusal the agent waits for its next cycle, and waits longer for each refusal in a row, up to an hour.

EvoHub supports the current agent protocol and the one before it. An agent too old for EvoHub logs `this agent is too old for EvoHub: upgrade it`.

## Releases

Agent versions are EvoHub's release versions, `YY.MM.N`: `26.10.1` is October 2026's first release. No `latest` image or chart is published, and the agent never upgrades itself, so the agent you run changes only when you upgrade it. Images, charts and binaries are signed with Sigstore; see each install page for how to verify them.

## Billing

Agents are free. Catalog is billed per watched environment. See [Catalog overview](https://docs.evohub.io/catalog-overview.md#billing).

## Related

- [Install on Kubernetes](https://docs.evohub.io/agent-kubernetes.md)
- [Install on a VM](https://docs.evohub.io/agent-vm.md)
- [What the agent sends](https://docs.evohub.io/agent-data-and-redaction.md)
- [Get started with Catalog](https://docs.evohub.io/catalog-getting-started.md)