Server Agent: Host Metrics Monitoring
Updated: 2026-08-04
The Server Agent is a small binary you install on your own machines to collect host-level metrics — CPU, memory, load average, disk, and network — and see them on a dedicated dashboard, alongside your monitors and incidents.
Unlike regular monitors (which check a URL from the outside), the Server Agent runs on the host itself and reports what it sees from the inside.
When to use it
Use the Server Agent for:
- Watching resource pressure on servers that back your monitored services (database boxes, app servers, workers)
- Catching a slow memory leak or disk-fill-up before it takes a service down
- Correlating a host running hot with an incident that happened around the same time
If you need to check that a website or API is reachable, use a regular monitor instead. If you need to confirm a scheduled job actually ran, use a heartbeat monitor.
Installing the agent
- Go to Servers in the dashboard and click Add server.
- Give it a name (a label for you — the agent’s own hostname is separate, optional, and can be changed or cleared later).
- Creating the server returns a one-time install command:
curl -fsSL https://statuspage.me/install-server-agent.sh | sudo bash -s -- \
--server-id <server-id> \
--ingest-key <ingest-key>
Run that on the target host. The --ingest-key is shown exactly once at creation time and cannot be retrieved later — copy it before closing the dialog. If you lose it, regenerate a new one from the server’s Settings.
The agent is open source: github.com/hosted-status-page/hsp-server-agent. Read the install script and the agent’s source before piping it into sudo bash, same as you should for any curl-to-shell install.
Metrics typically appear on the dashboard within a couple of minutes of a successful install.
Metrics collected
The agent reports, on a regular interval:
- CPU — user and system utilization
- Memory — used bytes
- Load average — 1, 5, and 15 minute averages
- Disk — used bytes, read/write throughput
- Network — inbound/outbound throughput
Each metric has its own chart on the server’s detail page, with a range picker (1h / 6h / 24h / 7d / 30d) to zoom in or out. How far back you can look depends on your plan’s metrics retention window.
Dashboard
Server list (/user/servers)
Every server you’ve added shows as a card with its current status, at-a-glance CPU/memory/load, and when it was last seen. A quota indicator at the top shows how many of your plan’s server slots are in use.
Status meanings:
- Online — reporting normally
- Stale — hasn’t reported in a while, but not yet considered down
- Offline — stopped reporting
- Pending — added, but no report received yet
Server detail (/user/servers/:id)
Click into a server to see its full metric charts, configure threshold alerts, and open Settings.
If a server is linked to a status page, incident windows from that page are shaded directly on its metric charts — useful for spotting “was this host struggling when that incident happened?” at a glance. See Linking a server to a status page below.
Threshold alerts
On a plan that includes server alerts, you can add threshold rules from a server’s detail page: pick a metric (e.g. cpu_user_pct, mem_used_bytes, load1, disk_used_bytes, net_rx_bps), a condition (above / at or above / below / at or below), a threshold value, and how long the condition must hold before it fires (so a brief spike stays quiet).
A rule shows Firing while its condition is met, OK once it clears, or Disabled if you’ve turned it off. Alerts are sent through the same internal notification channels used for your monitor and heartbeat alerts.
If your plan doesn’t include server alerts, the detail page shows an upgrade prompt instead of the “Add rule” button.
Server settings
Open a server and click the gear icon to manage it:
- Name, hostname, description — edit anytime. Hostname is self-reported by the agent and may carry a machine’s real name; clear or edit it if you’d rather not keep that.
- Enabled — turn off to pause metrics collection without deleting anything.
- Status Page / Component — see Linking a server to a status page below.
- Regenerate ingest key — issues a new key and immediately invalidates the old one. You’ll need to update the key in the agent’s config on the host.
- Delete — permanently removes the server and all its recorded metrics. This cannot be undone.
Linking a server to a status page
From the same Settings panel:
- Status Page — pick one of your status pages, or “— None —” to unlink. This alone only enables incident-window shading on the server’s own charts (dashboard-internal); nothing changes on your public page.
- Component (optional) — also picking an existing component on that page makes this server’s metrics public: a small “Infrastructure” widget appears on your status page showing that component’s CPU, memory, and disk usage. Only the component name is shown — never the server’s own name, hostname, or IP. This option only appears on plans that include public host metrics; other plans see an upgrade badge instead.
A linked server shows a Public badge (component picked) or nothing extra (status page only, correlation-only) next to its name on the detail page.
The status page’s own Settings → Servers tab lists every server linked to it, each tagged Public or Correlation only, with a link back to that server’s Settings to change or remove the link — editing always happens from the server’s side.
Plan limits
Server Agent capacity depends on your plan:
- Server count — how many hosts you can add
- Metrics retention — how far back historical metrics are kept
- Threshold alerts — whether you can configure alert rules
Check Billing & Plan for your current limits.
Troubleshooting
- “No data for this range” right after install: give it a couple of minutes for the first report to arrive, then try a shorter range.
- A server shows Stale or Offline: check that the agent process is still running on the host and that outbound HTTPS to your StatusPage.me instance isn’t blocked.
- Lost the ingest key: you can’t retrieve the original — regenerate one from Settings and update the agent’s config on the host.
- Install command 404s: make sure you’re using the exact command shown when the server was created — it’s tied to that server’s ID and key.
Security notes
- The ingest key authenticates the agent to your account — treat it like a password, and avoid logging it in CI/CD output.
- Hostnames are self-reported and may contain personal information (a machine named after a person, for example); they’re never shown on a public page and can be edited or cleared at any time.
- Regenerate the ingest key immediately if you suspect it leaked.
- The agent’s source is public: github.com/hosted-status-page/hsp-server-agent. Nothing it collects or sends is hidden from you.