Rolling out host agents
This page is for whoever has to put an agent on more than one machine. It covers the three routes people ask for - interface, API and MCP - and is explicit about which of them actually works today.
What the agent is
Section titled “What the agent is”A small binary that samples the host it runs on and pushes what it measured: CPU, memory, disk, and whether named services are running. It also serves as the host’s availability signal.
The agent executes nothing. No scripts, no commands, not as an opt-in. Everything it does is read-only observation of the machine it sits on. That is a deliberate boundary, not a missing feature - it is what lets you put it on a production host without a security review of what it might be told to run.
Route 1: the interface - the complete path
Section titled “Route 1: the interface - the complete path”Creating an enrollment token and installing an agent works end to end in the web app. This is the only route that does today.
The installer is a single command; the token identifies your organization:
PERSTAT_TOKEN=psag_… sh -c "$(curl -fsSL https://agent.perstat.io/install.sh)"What the installer verifies
Section titled “What the installer verifies”Before anything is installed, the script checks two things in this order:
- The release signature - an ed25519 signature over
SHA256SUMS, against a public key pinned inside the script. - The checksum of the downloaded binary against that verified list.
The order matters. A checksum list on its own only proves that the binary and the list belong together - an attacker who controls the distribution host can replace both. The signature is what makes the list trustworthy.
If SHA256SUMS.sig is missing, the installer refuses to install. A stripped
signature is exactly what a tampered mirror looks like. Development builds can
override this with PERSTAT_ALLOW_UNSIGNED=1; production installs should not.
The limit, named honestly
Section titled “The limit, named honestly”Running curl … | sh fetches the script from the same host it then verifies
downloads against. The signature check protects the binary, not the script that
performs it. If that distinction matters to you - and on a fleet it should -
download install.sh once, review it, and distribute it through your own
configuration management instead of piping it from the network on every host.
Route 2: the API - list and remove only
Section titled “Route 2: the API - list and remove only”The public API has exactly two agent operations:
| Method | Path | What it does |
|---|---|---|
GET |
/organizations/{org_id}/agents |
List the agents of an organization |
DELETE |
/organizations/{org_id}/agents/{agent_id} |
Remove an agent |
That is the whole surface. There is no public endpoint that creates an enrollment token, which means an agent rollout cannot be driven end to end by the API today. You can inventory a fleet and you can tear it down; you cannot provision it.
If you are automating a rollout, the working shape today is: mint one reusable token in the interface, then hand it to your configuration management as a secret. Everything after that is the install command above.
Removing an agent takes its monitors with it. This is intentional: a monitor tied to a removed agent would keep counting against your plan, would never receive another check, and - worst of all - an incident open at the moment of removal could never close by itself.
Route 3: MCP - not available
Section titled “Route 3: MCP - not available”The MCP server exposes fifteen tools covering organizations, projects, monitors, incidents and status pages. None of them touch agents. An agent can inspect and act on your monitoring, but it cannot enroll, list or remove a host agent.
Provisioning agents through the API and through MCP is a known request. It is not built, and this page will say so until it is.
Timing you should know before you go bug-hunting
Section titled “Timing you should know before you go bug-hunting”These numbers explain most “it isn’t working” reports on a fresh install:
| What | Interval |
|---|---|
| Sampling on the host | every 15 s |
| Push to Perstat | every 60 s |
| Config poll (agent asks for its settings) | about every 5 min |
| Freshness window for evaluating agent monitors | 180 s |
Two consequences worth internalising:
- A setting you change server-side takes up to about six minutes to reach the agent - the config poll plus one push cycle. Treat “no data yet” as waiting, not as failure, or you will build yourself false alarms right after creating a monitor.
- The agent buffers while it cannot reach us - roughly six hours of samples
- and delivers them on reconnect. A gap in the graph is not automatically a gap in the measurement.
What to put on each host
Section titled “What to put on each host”A sensibly watched host costs six to eight monitors: availability, CPU, memory, disk, plus one per service you care about. Each monitor is one incident, one line on a status page, one on-call alarm - that chain is the reason a monitor is not a bundle of checks.
Plan for that number before you roll out twenty hosts, because monitors are the unit your plan counts. See Plans and limits.
- Host agent - what the agent measures, in detail.
- Agents on a fleet - running agents at scale.
- MCP for agents - what the MCP server does expose.