Host agent check

What it verifies

A host agent monitor binds to one agent installed on one of your hosts and watches one metric. availability watches whether the agent still checks in. cpu, mem, and disk compare usage in percent with a threshold, and service checks that a named process is running. The agent reports to the control plane, and the server judges the latest report about every 30 s. A breach opens an incident, with a push per notify_push, or raises only an in-app notice, as breach_severity says. One agent carries several monitors, one per metric or process.

Use it when

• A host runs something with no port to probe, or the port still answers while the host is out of memory or disk.
• A process must keep running: a database, a queue worker, or a reverse proxy. A restart shorter than the grace does not count as a breach.
• A host should raise an alarm when it stops reporting at all, with a grace so a reboot inside the grace opens no incident.

The check measures nothing over the network. Reachability of a port or URL from the internet needs the ping, TCP, or HTTP(S) check. A cron job or batch run without a process to watch needs the heartbeat check.

Swipe sideways to inspect the product view.

app.perstat.io

Configuration

Agent. No network target. The monitor binds to one host agent of your organization by its agent_id, and the form lists the registered agents. The report comes from the host, so the check takes no regions, no IP families, and no interval of its own.

How a check runs

1. The agent on the host reports to the control plane. About every 30 s, the server loads the agent’s latest report for this monitor. No probe region takes part, and the check never touches the host over the network.
2. availability: the server compares the age of the last report with grace_seconds. A report older than the grace is a breach.
3. cpu, mem, disk: judged only while the last report is at most 180 s old, and a value above threshold is a breach. Without a fresh value, the pass records no result instead of a false alarm. The silent host is the job of the availability metric.
4. service: judged only with a fresh report and a fresh entry for the named process. A process that has not been running for longer than grace_seconds is a breach.
5. breach_severity decides what a breach becomes: failed with severity critical, or degraded. Critical opens an incident with a push per notify_push, and degraded raises an in-app notice only. Alarm and recovery are fixed at 1 evaluation each, so the next pass decides.

What a result contains

State and severity

passed, degraded, or failed, with severity ok, degraded, or critical. The region is agent, the marker of a server-side check.

Detail line

One line with the judged fact. It shows the age of the last report against the grace, the value against the threshold (CPU 95% > 90%), or the process with its process count and CPU share.

Latency and response code

Nothing is measured over the network, so a result carries neither a response time nor a status code.

States and severity

• okThe last report is within the grace, the value is at or below the threshold, or the process is running.
• degradedA breach with breach_severity set to degraded. It is recorded and shown as an in-app notice, with no incident and no push.
• downA breach with breach_severity set to critical, the default. The agent stayed silent past the grace, a value rose above the threshold, or the process stopped for longer than the grace. It opens an incident, with a push per notify_push.
• errorAppears only in a test run. When the metric cannot be judged, for example without a fresh report, the run answers error with a diagnosis. Nothing is stored and no incident opens.
• pendingNo result yet, right after creation or while the agent has sent no fresh value for the metric. The pass records nothing rather than a false alarm.

The signal comes from your host or your job, without regions or quorum, so one missed report counts. Alarm and recovery are fixed at 1 evaluation each. The pass that sees the breach opens the incident, and one passing evaluation counts as recovery.

Plans and limits

Host agents

2 on Free, 10 on Pulse, 50 on Sentinel, and 200 on Command. Enterprise quotas are custom. An add-on pack adds 10 agents for €19.

Monitors per agent

25 on Free, Pulse, Sentinel, and Command. Enterprise quotas are custom. A host agent monitor counts here, not against the probe monitor quota.

Interval and regions

Not applicable. The server evaluates about every 30 s, and the plans’ interval floors and region counts do not apply to this type.

Compare every plan limit

From the pipeline or an agent

The same config works in the deploy step, in an MCP client such as Claude Code, and in the form above. create_monitor needs an organization-wide API key. If you omit regions, the plan picks its default.

{
  "name": "web-01 CPU",
  "type": "agent",
  "config": {
    "agent_id": "agt_...",
    "metric": "cpu",
    "threshold": 90,
    "breach_severity": "degraded",
    "notify_push": true
  }
}

Every interface, with its boundary

Limits

• The agent reports four metrics (availability, CPU, memory, and disk) and the state of a named process. Other metrics and custom values are not available.
• CPU, memory, and disk are not judged while the agent is silent. Pair a threshold monitor with an availability monitor on the same agent to catch the silent host.
• grace_seconds is set over the API or MCP. The form keeps the stored value when you edit.
• The type has no interval, regions, or alert policy of its own, and the form hides all three. The server evaluates all agent monitors in one pass about every 30 s and ignores regions in a request. interval_seconds is stored on an edit and shown in the monitor, but the evaluation reads neither that value nor the 60 s set at creation.
• agent_id must name an agent already registered in your organization. The ID comes from the agent registration, and the monitor does not create it.

Related check types

• Heartbeat checkA secret URL your job calls on schedule. Silence past period plus grace, or a reported failure, marks it down.
• Ping checkReachability of a host over ICMP echo: replies, loss, and average round trip from every region.
• TCP port checkWhether a port accepts a connection, optionally with the certificate served on it.

All check types