BoxWatch
Sign in

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 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.

Every account gets a 5-minute push interval and 30-day retention, free.

The cron entry on every host runs every minute. The API accepts one heartbeat every 5 minutes and discards extras (while still refreshing server-side metadata).

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. 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

  1. In the dashboard, click Add server. Pick a name and (optionally) a group.
  2. Copy the install command from the modal. The agent key is baked into it.
  3. 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:

  1. In the dashboard, delete the server from the server list. This drops all stored metrics and unbinds the agent key.
  2. 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

Every account supports up to 100 servers. Adding a server beyond that cap returns 402 from the API. Existing servers keep reporting. See Limits & features.

What's next

Was this page helpful?
← Previous
Limits & features
Next →
Installing the agent