Health Checks

Health checks let you point Perch at any HTTP or HTTPS endpoint and track whether it’s up, how fast it responds, and how reliable it’s been over time. Think of it as a lightweight Uptime Kuma baked right into your dashboard.

Creating a health check

Head to Health Checks in the sidebar and hit New Check. There are three things to fill in:

Name it

Whatever you want to call it in the dashboard, like “API”, “Homepage”, or “Auth Service”.

Add the URL

The endpoint to check. It needs to be reachable from the machine running the hub, and it has to be a public address (more on that below).

Set the interval

How often to run the check, in seconds. 60 seconds is a solid default.

Hit Save and the check starts running right away.

What the dashboard shows

Each check gets its own card on the Health Checks page with:

  • Status dot: green and pulsing when it’s up, red when it’s down
  • Uptime %: calculated over the last 90 results
  • Avg latency: average response time across recent checks
  • Heartbeat bars: a row of 90 colored slots for the last 90 results, newest on the right. Green is up, red is down, grey is pending or no data yet.

Click into any check to open its detail page, which has a full response-time chart and a paginated results table of what happened and when.

How checks fire

The first check runs the moment you save, not after the first interval. So even with a 60-second interval, you’ll have your first result within a couple of seconds of creating the check.

After that, checks run on the interval you set. Each result stores the timestamp, the HTTP status, the response time in milliseconds, and whether it counted as up or down.

What counts as “up”

A check is up when the endpoint returns an HTTP 2xx success response within 10 seconds. Redirects are followed automatically. Anything else counts as down, whether that’s a 4xx or 5xx status, a timeout, a connection refused, or a DNS failure.

What Perch can actually reach

This one trips people up, so it’s worth calling out.

Health checks only hit public URLs

Checks run from the hub container, and Perch deliberately blocks any URL that resolves to a private or internal address (localhost, RFC 1918 ranges like 10.x / 172.16-31.x / 192.168.x, link-local, and cloud metadata IPs). This is the same SSRF protection that keeps your hub from being tricked into probing your internal network. See Security for the full picture.

In practice that means you can only check endpoints that are reachable on the public internet. To watch something on a private network, you’d expose it publicly (behind its own auth) or wait for agent-side health checks, which are on the roadmap but not a thing just yet.

Alerts on health checks

Want a ping when a check goes down or recovers? Point an alert rule at it. See Alerts for how to wire that up.