Agent Monitors

Lightweight server monitoring agents that report system metrics back to Hoppla. Track CPU, memory, disk usage, and load average without configuring complex infrastructure monitoring tools.

How It Works

Install the Hoppla agent on your server. The agent runs as a background service and periodically sends a heartbeat with system metrics to Hoppla. You can configure thresholds for each metric to receive warnings when resources are running low.

If the heartbeat stops entirely (e.g., the server goes down), an incident is created -- similar to how cron monitors work.

Getting Your Token

First, create the monitor and grab its token:

1. Go to Monitors and click Add Agent Monitor.
2. Copy the generated agent token. You will pass it to the agent during setup.

The dashboard shows the exact, ready-to-paste commands for each install method below, pre-filled with your token.

Installation

Pick whichever method fits your server. They all report the same metrics -- choose the one that matches your environment.

Shell script

A self-contained shell agent. Good for any Linux/macOS server with curl and standard tools:

curl -sSL https://releases.hoppla.dev/agent/hoppla-agent.sh -o hoppla-agent.sh
chmod +x hoppla-agent.sh
./hoppla-agent.sh --token YOUR-AGENT-TOKEN

Go binary

A single static binary -- no runtime dependencies. The installer downloads the right build for your platform:

curl -sSL https://releases.hoppla.dev/agent/install.sh | sh
hoppla-agent --token YOUR-AGENT-TOKEN

PHP probe

A drop-in PHP script for servers that already have PHP. Useful on shared or PHP-centric hosting:

curl -sSL https://releases.hoppla.dev/agent/hoppla-probe.php -o hoppla-probe.php
php hoppla-probe.php --token YOUR-AGENT-TOKEN

WordPress plugin

For WordPress sites, install the Hoppla plugin, then paste your agent token into its settings. The plugin reports your server's metrics on a schedule -- no shell access required.

Configuration

The agent accepts its settings as command-line flags (or, for the shell and Go agents, the matching environment variables):

Flag	Env variable	Required	Default	Description
--token	HOPPLA_TOKEN	Yes	--	Your agent token from the dashboard.
--interval	HOPPLA_INTERVAL	No	60	Reporting interval in seconds. Allowed values: 30, 60, or 120.

To keep the agent running across reboots, run it as a systemd service:

# /etc/systemd/system/hoppla-agent.service
[Unit]
Description=Hoppla Server Agent
After=network.target

[Service]
ExecStart=/usr/local/bin/hoppla-agent --token YOUR-AGENT-TOKEN
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now hoppla-agent

The agent registers itself with Hoppla and begins reporting metrics immediately.

Log Files

The agent can also read web server and application logs. Which files it may read is decided on the server itself, not in the dashboard: a log source configured in the dashboard only selects among the files the host allows.

• Everything under /var/log/ is allowed by default.
• To allow other files, add one absolute path or glob per line to a file in /etc/monitor-agent/log-paths.d/, or list them in MONITOR_AGENT_LOG_PATHS (separated by :). A trailing /** allows everything below a directory.

# /etc/monitor-agent/log-paths.d/app
/srv/app/storage/logs/*.log
/home/deploy/sites/shop/logs/**

The agent reads regular files only. It follows a symlink only when the file it points to is allowed as well. A refused file shows up in the dashboard as an unhealthy log source, with the reason. Run the agent as an unprivileged user, as in the service file above; give it read access to a log through the file's group, never by running it as root.

Monitored Metrics

The agent collects and reports the following system metrics:

Metric	Description	Unit
CPU Usage	Current CPU utilization	Percentage (%)
Memory Usage	RAM utilization	Percentage (%)
Disk Usage	Filesystem utilization (per mount point)	Percentage (%)
Load Average	System load (1m, 5m, 15m)	Numeric

Each report also includes the hostname, operating system name, and the agent version, so you can tell your servers apart at a glance.

Metrics are displayed on the agent monitor detail page with historical charts, so you can spot trends and capacity issues over time.

Thresholds

Configure warning and critical thresholds for each metric to get alerted before problems escalate.

Metric	Warning Default	Fail Default
CPU Usage	70%	90%
Memory Usage	80%	95%
Disk Usage	80%	95%
Load Average	2.0 per core	5.0 per core

You can customize these thresholds per monitor in the dashboard under the monitor's settings.

Alerts

Agent monitors produce two types of alerts:

Resource Warnings

When a metric exceeds the configured warning or critical threshold, a Server Resources warning event is fired. This sends notifications to your configured channels with details about which metric is elevated and its current value.

Warnings are automatically cleared when the metric drops back below the threshold.

Heartbeat Failures

If the agent stops sending heartbeats (because the server crashed, the network is down, or the agent process stopped), an incident is created after the configured grace period. This works identically to cron monitor heartbeat detection.

The incident is automatically resolved when the agent resumes sending heartbeats.