Checks
Server agent
A Server check watches machines from the inside. A small Bash script, the server agent, runs on each Linux server and reports its CPU, memory, disk, network, and the processes you name. You get an alert when a rule holds for as long as you set, and when servers stop reporting.
Use it next to an outside check, not instead of one. An HTTP check tells you the site stopped answering. The agent tells you the disk was at 94% an hour before.
One Server check covers one server or a whole fleet. Every machine that runs the install command joins the same check, so a web tier behind an autoscaler is one check, not one per instance.
Why server checks: Linux server monitoring sums up what the agent covers and what each plan includes.
Plans
| Free | Pro | |
|---|---|---|
| Servers per Server check | 1 | 25 |
| Report interval | 5 minutes | 1 minute |
| Metric history in the console | 7 days | 30 days |
A Server check counts as one check toward the plan's check limit, however many servers report to it.
Add a Server check
- Open Checks, click Add check, and pick Server.
- Fill in Name (placeholder
Production web servers). - Set Servers that must report. The default is 1. For a fleet, use the smallest number of healthy servers you can live with.
- Set Grace before down: how long the check may sit below that number before it goes down. Default 5 minutes; None goes down at once. The grace is what keeps a reboot or a rolling deploy from alerting.
- Click Add check. The check page opens with the install command.
The install command holds the check's enrollment token and is shown once. Copy it before you click Done. Lost it? New install command on the check page makes a new token; servers already reporting keep working, and the old command stops adding servers.
Alerts and Status page work as on any check. See Alerts and Status page.
Install the agent
Run the install command on each server, as root:
curl -fsSL https://quickstatus.dev/agent/install.sh | sudo bash -s -- --token qse_...
The installer sends a first report before it finishes, so a wrong token fails right there. The server shows up on the check page within a minute.
- Supported: Ubuntu, Debian, RHEL, Rocky, Alma, Amazon Linux, Alpine, and openSUSE, on x86_64 and arm64.
- It runs as its own unprivileged
quickstatususer from a systemd timer (cron when there is no systemd). No daemon and no open ports. It only sends; QuickStatus.dev never connects to your server. - It needs
bash,curl,gzip,awk, anddf. The installer adds any that are missing. - To keep the token out of the process list and shell history, put it in a root-only file and pass
--token-file /root/qs-tokeninstead of--token.
| Option | Use |
|---|---|
--token TOKEN |
Enrollment token (or set QUICKSTATUS_TOKEN) |
--token-file PATH |
Read the token from a file |
--token-aws-ssm NAME |
Read it from AWS SSM Parameter Store |
--token-aws-secret ID |
Read it from AWS Secrets Manager |
--token-gcp-secret NAME |
Read it from Google Secret Manager |
--processes "nginx postgres" |
Processes to watch, for Process down rules |
--labels env=prod,role=web |
Labels shown in the console |
--version X.Y.Z |
Install a specific release. Pin this in Terraform or CloudFormation |
--wait |
Fail the install if the first report is not accepted |
--no-start |
Install and configure only |
Running the installer again upgrades the agent and keeps the settings you don't pass. The agent never updates itself; the Servers table marks an old agent with (update available).
The agent is open source (MIT) at github.com/QuickStatusHQ/quickstatus-agent. Its README covers verified installs against SHA256SUMS, Docker, a Kubernetes DaemonSet, and machine images.
Autoscaling groups and Terraform
Put the install command in the launch template's user data. Every instance enrolls with the same token and is identified by its cloud instance id, so a reused hostname is still a new server. Keep the token in SSM or Secrets Manager rather than in the user data:
curl -fsSL https://quickstatus.dev/agent/install.sh | bash -s -- \
--token-aws-ssm /quickstatus/web-token --version 0.1.0 --labels env=prod,role=web
Don't bake the agent into an AMI or VM template. Install it at boot so each machine gets its own secret.
Remove a server
On the server, run the uninstaller. It tells QuickStatus.dev the server left on purpose, then removes the agent:
curl -fsSL https://quickstatus.dev/agent/uninstall.sh | sudo bash
Or click Remove on its row in the Servers table.
What it reports
Every report covers the whole interval since the last one, not a one-second sample:
- CPU: usage, iowait, steal, load (1, 5, 15 min), core count
- Memory: RAM used, available, swap used
- Disk: per mount, used and inodes used, read and write rates
- Network: per interface, receive and send rates
- Processes: total count, and for each name you watch, whether it runs and how many instances
- Host: hostname, OS, kernel, uptime, agent version
It never reads logs, files, or application data, and of other processes it reads only their names. Every field it sends is listed in PAYLOAD.md.
When servers stop reporting
Each server on the check page is Reporting, Left, or Lost.
| State | Meaning |
|---|---|
| Reporting | Its last report arrived on time |
| Left | It shut down cleanly (scale-in, reboot, upgrade) and said so |
| Lost | It missed three reports in a row without leaving |
The check goes down when fewer servers than Servers that must report are reporting for longer than Grace before down. For a single server, that means a crash or lost network goes down once it is lost, and a clean shutdown that doesn't come back goes down after the grace.
A server that leaves never alerts by itself, so an autoscaler scaling in is quiet. Servers that left are hidden from the table until you click Show servers that left on purpose. Servers that left or were lost are deleted after 7 days.
Alert rules
Alert rules on the check page decide when metrics alert. A new Server check starts with three:
- CPU above 90% on any server for 10 min
- Memory above 90% on any server for 10 min
- Disk above 90% on any server, right away
Click Edit rules to change them, add more, or turn one off. Each rule has:
| Part | Choices |
|---|---|
| Metric | CPU, Memory, Disk, Swap, Inodes, Load (1 min), or Process down |
| Mount or Process name | Optional for Disk and Inodes (blank means every mount); required for Process down, for example nginx |
| Above or below and Threshold | A percentage, or a number for load |
| Scope | any server, fleet average, or at least N servers |
| For | right away, or 1 minute to 1 hour |
| Severity | Alert only leaves the check up. Mark down takes it down |
A rule alerts once when it has held for the whole duration, names the servers involved, and alerts again when it clears. It clears on its own when the server behind it leaves or is lost. Saving changed rules starts their timers over.
With no rules, servers are still watched for going silent.
Read the check page
- The top line shows Servers (reporting, of how many are needed), CPU and memory averages, the fullest disk, and any lost servers.
- Servers lists each machine with its state, CPU, memory, disk, load, watched processes, and last report.
- Metrics charts CPU, memory, fullest disk, load, and network over 1 hour, 6 hours, 24 hours, 7 days, or 30 days (Pro). Pick one server or All servers; with more than one, charts show the average and the busiest server.
- Pause stops alerts. Reports are still kept, and nothing alerts until you resume it.
From an agent or the API
- MCP:
create_checkwithkind: "server"returns the install command once, so a coding agent with a shell on the server can finish the setup.get_check_resultswithview: "servers"answers "which server is out of disk?", andview: "metrics"returns the charts. - API: create the check with
"type": "server", then manage machines, rules, a new install command, and metrics under/v1/endpoints/{id}.
Alert rules are edited in the console or over the API, not over MCP.
Not in this release
- GPU metrics and local model server checks (Ollama, vLLM) are planned.
- Linux only. No macOS or Windows agent.