Skip to main content

How it works

The agent has one job: know the host, run the probes the server asks for, and stream the results out. Everything below happens on the box with no inbound connections.

The transport​

The agent holds a single persistent WebSocket to the server, secured with TLS and certificate pinning. The endpoint and the pin are baked into the binary at build time, so there is no server address in any file on the host to tamper with. Because the connection is outbound, the host needs no open ports and works behind NAT.

Metrics, heartbeats, discovery facts, check results and traces all flow up this one connection. Config, commands and service definitions flow down it. If the server hears nothing for a few minutes, it sends a "collect now" request down the same socket. If the socket drops, that is the down signal: the server knows the host or agent is gone.

Discovery, then matching​

On start and on a schedule, the agent enumerates the host:

  • running processes (name, command line, binary path),
  • listening TCP and UDP ports with the owning process,
  • installed packages (dpkg, rpm, apk, brew),
  • service units and their state,
  • the init system in use,
  • scheduled jobs (cron).

These are called facts. The agent sends them up. The server holds a catalog of signed service definitions, each with a match rule (for example "process is nginx" or "unit is W3SVC"). When a host's facts match a definition, the server pushes that definition down and the agent activates its probes. Nothing runs that was not matched and signed.

Probes​

A definition is a set of probes expressed with a small set of primitives: run an allow-listed command and parse it, make an HTTP call, run a SQL query, read a file, tail a log, connect to a port, walk SNMP, and a few more. The agent executes these locally and turns the output into metrics and facts using the names the definition specifies. For the small share of services that cannot be expressed declaratively, there is a compiled Go fallback probe built into the agent.

What leaves the host​

Metrics, discovery facts, check results, events and traces leave the host. The values of secrets never do. A definition references a credential by name; the agent resolves that name locally at probe time and builds the connection string on the box. The server sees metrics and service names, never passwords.

Identity and trust​

At registration the agent exchanges a shared team key for a per-server key and a UUID. That per-server key is what authenticates the WebSocket, and it rotates every 7 days. The key is stored encrypted at rest, bound to the machine, so a copied identity file is useless on another box. See Security model for the full picture.