title: "Server monitoring overview" description: "What the BoxWatch agent collects, how often, and how long it sticks around." last_updated: "2026-05-24"

Server monitoring overview

Server monitoring is the core of BoxWatch. You install an agent on a Linux host, it pings the API on a cron tick, and you get CPU, memory, disk, load, network, and process data in the dashboard. There are no daemons and no inbound ports.

This page is a tour of the whole pipeline. The pages linked below cover individual pieces in depth.

The pipeline

+--------+   HTTPS POST   +-----+   read   +-----------+
| agent  | -------------> | API | <------- | dashboard |
+--------+                +-----+          +-----------+
   cron                     |
                            |
                            +--> alerts (email, Slack, Discord, webhooks)

Every minute, cron triggers /opt/boxwatch/agent.sh. The agent collects a snapshot, builds a JSON body, and POSTs it to https://api.boxwatch.app/agent/heartbeat using the server's agent key. The API applies a plan-based rate limit, stores the metrics, runs alert checks, and returns a small response that tells the agent what watched processes and uptime checks to run next time.

The agent does not run continuously. There's no socket and no inbound port to open.

Push interval and retention

Push interval is the minimum time between accepted heartbeats. Send more often and the API returns 429 with info_updated: true — the server-side state (hostname, agent version) is still refreshed, but no new metric row is written.

Retention is how long BoxWatch keeps your historical metrics. Older rows roll off automatically.

Plan	Push interval	Retention
Hobby	60 minutes	24 hours
Pro	5 minutes	7 days
Team	5 minutes	30 days
Scale	1 minute	90 days

The cron entry on every host runs every minute. Plan tier is what gates how often the API accepts the data. You don't change cron when you upgrade — the server side adapts.

What the agent collects

Every accepted heartbeat captures:

CPU usage — overall percent busy.
Memory usage — percent used of total RAM.
Disk usage — root mount as a percent. The first mount under /mnt (if present) is reported separately.
Load averages — 1, 5, and 15 minute load.
Network — cumulative rx_bytes and tx_bytes on the default-route interface.
Kernel uptime — seconds since boot.
Hostname, IP, OS string, agent version — refreshed every heartbeat.
Watched processes — count, CPU, RSS, and oldest start time for each process you've configured. See Process monitoring.
Uptime check results — HTTP/TCP/TLS probe results for any checks assigned to this server. Pro+ See Synthetic uptime checks.

A heartbeat with no processes or uptime checks configured is around 500 bytes on the wire.

What it doesn't collect

BoxWatch is host-level. It does not collect:

Application-level metrics like request rates, queue depth, or DB query timings. Use a metrics library (StatsD, OpenTelemetry, Prometheus client) for those.
Log lines or log searches. Use a logging service.
Distributed traces. Use a tracing service.

If you need any of those, BoxWatch sits alongside them — same servers, separate tools.

Adding a server

In the dashboard, click Add server. Pick a name and (optionally) a group.
Copy the install command from the modal. The agent key is baked into it.
SSH into the host and paste the command.

curl -sL https://boxwatch.app/install.sh | bash -s YOUR_AGENT_KEY

Within a minute or two, the server's row in the dashboard fills in with hostname, OS, and the first metric points. See Installing the agent for the full install reference, including manual installation and what files land where.

Removing a server

Two steps:

In the dashboard, delete the server from the server list. This drops all stored metrics and unbinds the agent key.
On the host, run the uninstaller to stop the cron entry and remove /opt/boxwatch:

curl -sL https://boxwatch.app/uninstall.sh | bash

If you delete the dashboard row but leave the agent installed, the agent will get a 401 on its next heartbeat and stop writing to your account. It won't break anything, but the cron will log errors. Uninstall it.

Plan caps

Plan limits are tracked separately from billing — adding a server beyond your plan cap returns 402 from the API. Existing servers keep reporting if you downgrade. See Plan tiers & limits.

What's next

Installing the agent — install, upgrade, uninstall, troubleshoot.
Server groups — logical groupings for filtering and bulk maintenance.
Maintenance windows — silence alerts during planned work.
Disk full projection — get warned before a disk fills up.
Uptime SLA — rolling uptime percentages per server.