Agents

Agents

Agents collect platform state and push reports to the Trove server.

They are intentionally small. Each concrete agent implements platform discovery. Shared scheduling and HTTP push logic lives in Agentkit.

Supported agents

Agent	Watches	Typical deployment
Docker	Docker containers on one Docker host	container on each Docker host
Kubernetes	workloads and pods in one cluster	in-cluster Deployment
Proxmox	VMs and LXCs across one Proxmox cluster	container or service outside/near Proxmox
Local	systemd units/process-style services on one Linux host	systemd service on the host

One agent per scope

Run agents by data scope:

• one Docker agent per Docker Engine
• one Kubernetes agent per Kubernetes cluster
• one Proxmox agent per Proxmox cluster
• one Local agent per Linux host

A Proxmox agent discovers all nodes in the cluster from one API endpoint. Do not run one Proxmox agent per node unless you intentionally want duplicated views.

Common configuration

Every agent supports:

Variable	Required	Default	Purpose
TROVE_SERVER_URL	yes	none	Base URL of the Trove server.
TROVE_TOKEN	yes	none	Agent token created by the server.
TROVE_INTERVAL	no	30s	Push interval. Accepts Go duration or bare seconds.
TROVE_AGENT_NAME	no	hostname	Name in the report envelope. The dashboard agent name comes from agent create; for the local agent this also becomes the host name.

Use a server address that is reachable from where the agent runs.

The most common mistake is setting:

TROVE_SERVER_URL=http://localhost:8080

from inside a container, pod, or different host. In that case localhost means the agent itself, not the Trove server.

Report behaviour

Agents push once immediately on startup, then once per interval.

Each push is a full-state report. That means:

• services present in the report are inserted or updated
• services missing from the report are marked removed
• changed service state records a state event
• changed service health records a health event

If collection fails, the agent logs the failure and tries again on the next interval.

If collection succeeds but returns zero hosts, agentkit logs a warning because this usually means a permissions issue or wrong target.

Read-only promise

Agents are written to collect only.

They should not:

• restart workloads
• exec into containers or pods
• modify labels
• patch Kubernetes resources
• change Proxmox guest state
• write to Docker
• manage systemd units

When adding or changing an agent, keep the platform API access read-only.

Platform-specific pages

• Docker-Agent
• Kubernetes-Agent
• Proxmox-Agent
• Local-Agent