title: "Quickstart" description: "Install the BoxWatch agent and see your first heartbeat in 60 seconds." last_updated: "2026-05-24"

Install in 60 seconds

BoxWatch is a push-model monitoring agent. You install a small bash script on each server. It pings BoxWatch every minute with CPU, memory, disk, and network metrics. You see those metrics in your dashboard, and you get alerts when something looks wrong.

There's no inbound port to open, no daemon to keep running, no SDK to import. It's a cron job that posts JSON.

1. Sign up and add a server

Create an account at boxwatch.app. In the dashboard, click Add Server. Give it a name, choose a group if you want, and BoxWatch will generate an agent key for you.

The "Add Server" modal shows the exact install command, with your key baked in. Copy it.

2. Run the install command

SSH into the server you want to monitor and paste the command:

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

The installer needs root (it'll use sudo if you're not root already). It requires curl. It works better with jq installed — without it, watched-process and uptime-check sync are skipped. Everything else works either way.

The installer drops the agent at /opt/boxwatch/agent.sh, writes a config file with your key, and adds a cron entry that runs the agent every minute.

sudo /opt/boxwatch/agent.sh

3. Watch metrics flow in

Refresh your dashboard. Within a minute or two you'll see the server's hostname, IP, OS version, and the first metric points. Within 10 minutes you'll have enough data to plot trends.

4. Set up alerts (optional)

Out of the box, BoxWatch will alert you if a server stops reporting. To get more specific — CPU over 80%, disk over 90%, a process crashed — head to Alerts in the dashboard. The Alerts & Notifications docs (coming soon) cover the full list.

What just happened?

• A cron entry was added to /etc/cron.d/ that runs /opt/boxwatch/agent.sh every minute.
• The agent collects metrics from /proc, top, df, and ss (or their BSD equivalents).
• It POSTs them to https://api.boxwatch.app/agent/heartbeat with your agent key.
• The response includes any watched-process or uptime-check assignments, so the agent knows what else to look at on the next run.

You can read the script before you install it — it's public and short.

Next steps

• Core concepts — what every object in the dashboard means
• Cron heartbeat monitoring — watch your scheduled jobs
• Plan tiers & limits — what each plan includes