Rolling out host agents
Written for whoever puts agents on more than one machine. Enrollment runs in the app, the REST API handles the inventory and removal, and the REST API or MCP creates the monitors on top.
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 even as an opt-in. Everything it does is read-only observation of the machine it sits on, so you can put it on a production host without reviewing what it might be told to run.
Route 1: the app, end to end
Section titled “Route 1: the app, end to end”The web app covers the whole path, from the enrollment token to a running agent.
The installer is a single command, and 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 proves that the binary and the list belong together, and an attacker who controls the distribution host could replace both. The signature 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, and production installs keep the check.
Review the script once for a fleet
Section titled “Review the script once for a fleet”curl … | sh fetches the script from the same host it then verifies downloads against, so the
signature check protects the binary, and the script itself comes from that origin. On a fleet,
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: REST API for inventory and removal
Section titled “Route 2: REST API for inventory and removal”With a scoped API key, the REST API covers the agent inventory:
| Method | Path | Scope | What it does |
|---|---|---|---|
GET |
/organizations/{org_id}/agents |
agents:read |
List the agents of an organization |
DELETE |
/organizations/{org_id}/agents/{agent_id} |
agents:write |
Remove an agent |
Enrollment starts in the app: you create the token there, and each host creates its own identity when it enrolls. To automate a roll-out, create one reusable token in the app and hand it to your configuration management as a secret. Everything after that is the install command above, and the monitors for each host come from the REST API or MCP.
Removing an agent archives its monitors. Their slots return to your plan, open incidents on them are resolved, and you can restore them paused, for example to point them at a replacement host.
Route 3: MCP for the monitors
Section titled “Route 3: MCP for the monitors”The MCP server’s seventeen tools cover organizations, projects, monitors, incidents, and status
pages. An AI agent creates and manages the monitors for each host, including agent monitors,
while enrollment and agent removal run through the app and the REST API.
Timings that explain a fresh install
Section titled “Timings that explain a fresh install”These numbers explain how a fresh install comes to life:
| 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 to plan for:
- A server-side change reaches the agent within about six minutes: the config poll plus one push cycle. Treat “no data yet” as waiting, and a new monitor settles without false alarms.
- The agent buffers roughly six hours of samples while it cannot reach Perstat and delivers them on reconnect, so the graph fills in after a short outage.
What to put on each host
Section titled “What to put on each host”A well-watched host uses six to eight monitors: availability, CPU, memory, disk, plus one per service you care about. Each monitor maps to one incident, one line on a status page, and one on-call alarm, which keeps every alert specific.
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: the tools for monitors and incidents.