Host agent

Download the Pingmon agent

A single small binary that reports CPU, memory, disk and detailed network statistics from your servers — and monitors the devices it can reach on their network. Latest version 0.5.0.

Before you install: get an enrolment key

Every host pairs with your account using an enrolment key. Sign in to Pingmon, open Agents and create one — have it to hand, because the installer asks for it.

One key can admit as many hosts as you like, so it belongs in a deployment script or a machine image rather than being created per machine. Each host that enrols is issued its own credential, so revoking a key later stops new hosts joining without disturbing the ones already reporting. Keys, and individual agents, are revoked from the same page.

What it needs

One outbound HTTPS connection — no inbound firewall rule. Nothing on this page is secret: the key is what grants access, and it is issued separately.

Choose your platform

Debian / Ubuntu

From the package repository recommended

The agent installs like any other package, and updates arrive with the rest of the machine's rather than needing anyone to remember it.

curl -fsSL https://pingmon.tech/apt/pingmon-agent-archive-keyring.gpg \
    | sudo tee /usr/share/keyrings/pingmon-agent-archive-keyring.gpg > /dev/null

echo 'deb [signed-by=/usr/share/keyrings/pingmon-agent-archive-keyring.gpg] https://pingmon.tech/apt stable main' \
    | sudo tee /etc/apt/sources.list.d/pingmon-agent.list

sudo apt update
sudo apt install pingmon-agent

The repository is signed, and the key above is what apt checks each update against. The package has no dependencies at all, so this works on old releases as well as current ones. Installing runs the pairing wizard — or supply PINGMON_SERVER and PINGMON_TOKEN in the environment to skip it.

On a machine with a desktop, a tray icon (pingmon-tray) starts at sign-in and shows whether the agent is reporting — KDE, XFCE, Cinnamon, MATE, and GNOME with the AppIndicator extension. On a server without a desktop it never runs.

Or a single package

For a machine that should not follow a repository — an image build, or a host with no route to this server at install time. It installs the agent, registers the service and then asks for your server address and enrolment key.

Debian / Ubuntu (x86-64) v0.5.0

Installs the binary and the systemd unit, then runs a short wizard that pairs the machine with your account. No dependencies — the binary is statically linked, so it installs on old and current releases alike. On a machine with a desktop, a tray icon shows whether the agent is reporting.

SHA-256 485f1c82424d81e54fe40d2d743ddf7692b497ce591797b4db2e16f69509947a

Download 1.4 MB

Debian / Ubuntu (ARM64) v0.5.0

The same package for ARM servers and single-board computers such as the Raspberry Pi 4 and 5 running a 64-bit OS.

SHA-256 b7c8ec8bff0fe61ec5e5b006031b0a970564b18717d72d54a533ce39f946156c

Download 1.4 MB

Then, in the directory you downloaded it to:

sudo apt install ./pingmon-agent_0.5.0_amd64.deb

To pair without being prompted — for a machine image or a configuration-management run — supply the details through the environment instead:

sudo PINGMON_SERVER=https://your-org.pingmon.tech \
     PINGMON_TOKEN=<your-enrolment-key> \
     apt install ./pingmon-agent_0.5.0_amd64.deb

Re-run the wizard at any time with sudo pingmon-agent-setup.

Upgrading and removing

From the repository it upgrades with everything else — apt upgrade, or whatever already runs unattended upgrades. A downloaded package upgrades by installing the newer one the same way: a paired machine is asked nothing and the service restarts into the new binary. Removing the package leaves the configuration in place, so reinstalling re-attaches the host to its existing device — only apt purge deletes it.

RHEL / Fedora / Rocky / Alma / SUSE

From the RPM repository recommended

The agent installs with dnf and stays current with everything else on the machine.

sudo rpm --import https://pingmon.tech/yum/pingmon-agent.asc

sudo tee /etc/yum.repos.d/pingmon-agent.repo > /dev/null <<'REPO'
[pingmon-agent]
name=PingMon Agent
baseurl=https://pingmon.tech/yum
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://pingmon.tech/yum/pingmon-agent.asc
REPO

sudo dnf install pingmon-agent

Both the packages and the repository index are signed with the same key as the Debian repository, which is what gpgcheck and repo_gpgcheck check respectively. The metadata is gzip rather than zstd and includes the sqlite indexes, so this works on RHEL 7-era yum as well as current dnf — on those systems use yum in place of dnf.

Or a single package

For a machine that should not follow a repository. Installs the binary and the systemd unit, then runs the pairing wizard.

RHEL / Fedora / Rocky / SUSE (x86-64) v0.5.0

Installs the binary and the systemd unit, then runs the pairing wizard. No dependencies, and a gzip payload rather than zstd, so it installs on RHEL 7-era systems as well as current ones. Use yum instead of dnf on RHEL 7.

SHA-256 730c4ac6326857bd7e15c211e5d95cd5b63c0c23d7c280133745a8cf4d410415

Download 1.9 MB

RHEL / Fedora / Rocky / SUSE (ARM64) v0.5.0

The same package for 64-bit ARM servers.

SHA-256 163fa71b174ba155baf55799a0990afeb00b482886337727f54fd2b848010e5c

Download 1.8 MB

Then, in the directory you downloaded it to:

sudo dnf install ./pingmon-agent-0.5.0-1.x86_64.rpm

PINGMON_SERVER and PINGMON_TOKEN in the environment skip the wizard here too.

Upgrading and removing

From the repository: dnf upgrade with everything else. A downloaded package upgrades by installing the newer one; a paired machine keeps its credentials and carries on. Removing the package leaves the configuration in place, so a reinstall re-attaches the host to its existing device.

Windows

One-line install quickest

From an elevated PowerShell prompt, with your enrolment key:

& ([scriptblock]::Create((irm https://pingmon.tech/downloads/install.ps1))) -Token <your-enrolment-key>

It downloads the newest agent, checks it against the published SHA-256 before running anything, installs it to Program Files\PingMon, pairs it with this server and registers the service. Run it again without -Token to upgrade a machine that is already paired. Read the script first — it is short, and you should.

Or download it

Windows (x86-64) v0.5.0

The agent and a PowerShell installer that copies it to Program Files, pairs it and registers the native "PingMonAgent" service (automatic start, restarts on failure), plus a tray icon that shows whether it is reporting. Windows Server 2012 / Windows 8 or newer. On a DHCP server it also reports active DHCP leases.

SHA-256 7e9b9b11082e9ea52828054df9ed78463091a803af2a2da1d32d10694b3d0b36

Download 1.2 MB

Windows executable only v0.5.0

The bare executable, for scripted or GPO deployment. Run "pingmon-agent.exe install --server … --token …" from an elevated prompt to pair it and register the native Windows service.

SHA-256 2f0402adb39bcd69b78e2fd8e427c71444f718fa320d014e264ac371345467e0

Download 1.9 MB

Unzip it, then from an elevated PowerShell prompt in that folder:

.\install.ps1 -Server https://your-org.pingmon.tech -Token <your-enrolment-key>

That copies the agent to Program Files\PingMon, pairs it, and registers the native PingMonAgent service — automatic start, restarted by Windows if it ever fails. No service wrapper is needed. The service logs to %ProgramData%\PingMon\agent.log. A tray icon starts at every sign-in: green when the agent is reporting, amber for a warning or an available update, red when it is stopped or cannot reach the server — with shortcuts to PingMon, the log, updates and a restart.

For scripted or Group Policy deployment, the executable does the same on its own: pingmon-agent.exe install --server … --token …, and pingmon-agent.exe uninstall removes the service.

On a DHCP server

On a Windows DHCP server — typically a domain controller — the agent also reports the server's active leases every five minutes (IP, MAC, DNS name, scope, reservations). Pingmon lists them so you can pick which of those devices to monitor, and the agent on that network then monitors them. With DHCP failover, install it on both partners; their reports are merged. See what it will send with:

& "$env:ProgramFiles\PingMon\pingmon-agent.exe" dhcp

Upgrading and removing

Download the newer zip and run .\install.ps1 again with no arguments: it stops the service, replaces the binary and starts it again, keeping the existing pairing. pingmon-agent.exe uninstall removes the service and leaves the configuration in %ProgramData%\PingMon, so a reinstall re-attaches to the same device.

Other Linux & platforms

Any Linux, tarball

For a distribution neither package format covers, an appliance, a container image, or a machine you administer by hand. Carries the binary, the service unit and an installer that does what the packages do.

Any Linux, tarball (x86-64) v0.5.0

For a distribution neither package format covers, an appliance, a container image, or a machine you administer by hand. Carries the binary, the service unit and an installer that does what the packages do.

SHA-256 4d260fde53adf01c585f1d7fd9ba67584ffc2c4afdf787da16bd1b9d38158987

Download 1.9 MB

Any Linux, tarball (ARM64) v0.5.0

The same archive for 64-bit ARM.

SHA-256 74b51bb4ca67d293c801fa83c740bf1f4ecb1d7e778e7987329ceb6c02427b70

Download 1.8 MB
tar xzf pingmon-agent-0.5.0-linux-amd64.tar.gz && sudo ./pingmon-agent-*/install.sh

Raw binaries

Linux (x86-64) v0.5.0

Statically linked. Runs on any Linux with kernel 3.2 or newer — no glibc requirement, so it works on older distributions as well as current ones.

SHA-256 91e16e67636d66150b02987f967b3117f1d95981b6d5dd1365e60e7cf05da30a

Download 2.2 MB

Linux (ARM64) v0.5.0

Statically linked, for ARM servers and single-board computers such as the Raspberry Pi 4 and 5 running a 64-bit OS.

SHA-256 47d354bb1730d07ba8d9383fc50559c7bcefef70a2e414dc6211d5a042a98d22

Download 1.8 MB

FreeBSD

Not yet published. The collector is written but has not been built or tested on FreeBSD — build it from source and please tell us how it goes.

build from source

Haiku

Not yet published. Haiku is a tier-3 Rust target with no prebuilt standard library, so it is built on Haiku itself. Use the native-tls feature.

build from source

Installing a raw binary

With your enrolment key to hand, on each host:

sudo install -m 0755 pingmon-agent-0.5.0-linux-x86_64 /usr/local/bin/pingmon-agent
sudo pingmon-agent enroll \
    --server https://your-org.pingmon.tech \
    --token <your-enrolment-key>

Then install the service unit for your platform and start it. Units for every platform are in the source's packaging/ directory.

Linux (systemd)

sudo cp pingmon-agent.service /etc/systemd/system/
sudo systemctl enable --now pingmon-agent

FreeBSD

sudo install -m 0555 pingmon-agent.rc /usr/local/etc/rc.d/pingmon_agent
sudo sysrc pingmon_agent_enable=YES
sudo service pingmon_agent start

Haiku

cp pingmon-agent /boot/system/non-packaged/bin/
cp pingmon-agent.launch /boot/system/settings/launch/pingmon-agent
launch_roster start pingmon-agent

To upgrade a raw binary, replace the file and restart the service.

Check it worked

The agent takes a baseline reading, waits, and sends its first report within a minute of enrolling. In Pingmon the machine then appears under Agents with the time of its last report, and gets a device page of its own carrying the host metrics.

Linux & other Unix

systemctl status pingmon-agent   # is it running?
pingmon-agent status             # paired to which server, as which device?

Windows (PowerShell)

Get-Service PingMonAgent
& "$env:ProgramFiles\PingMon\pingmon-agent.exe" status
Get-Content "$env:ProgramData\PingMon\agent.log" -Tail 30

If something looks wrong, two commands answer most of it without disturbing the service:

pingmon-agent once             # collect and print everything, sending nothing
pingmon-agent probe 10.0.0.1   # ping a device from this host, ignoring the server

Pinging other devices needs a ping or raw socket on Linux. The packaged service unit grants exactly that and nothing else; a hand-written unit may not, in which case the agent logs a warning, carries on reporting host metrics, and probes nothing rather than refusing to start. Windows uses the system ICMP service and needs nothing extra. Probing runs on Linux and Windows and is IPv4-only today — an IPv6 device is reported as unprobed rather than as down, because a device wrongly marked down wakes somebody at 3am and one honestly not covered does not.

Revoking an agent in Pingmon stops its credential working, wherever the machine has got to.

Verify a download

Every file's SHA-256 is on its card, and all of them are in SHA256SUMS:

sha256sum -c SHA256SUMS --ignore-missing           # Linux
Get-FileHash .\pingmon-agent-*-windows-x86_64.zip   # Windows: compare with the card

Reference

What it collects

Network, per interface (Linux)

Network, whole host (Linux)

Devices on the same network

The agent also pings the devices in your Pingmon account that it can reach, and reports the results as if Pingmon had pinged them itself. That is how equipment behind NAT or a firewall gets monitored: from the inside, by something that already has a route to it.

A device answers the agent, so the agent takes over pinging it and Pingmon's own poller steps aside — one measurement per device, not two. If the agent stops reporting, the poller picks the device back up on its own within a few minutes. Readings appear on the device page alongside everything else Pingmon knows about that host, and are kept for as long as your plan's retention allows.

DHCP leases (Windows DHCP Server)

Active leases only — IP, MAC, client name, scope, reservation, expiry — every five minutes, read through the DHCP Server Management API.

Building from source

The agent is a single Rust crate with no build step beyond Cargo. Service units for every platform are in packaging/.

cargo build --release

For a portable Linux binary, build against musl so the result does not depend on the build machine's C library:

rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

The Windows build cross-compiles from Linux with the MinGW toolchain:

rustup target add x86_64-pc-windows-gnu      # plus: apt install gcc-mingw-w64-x86-64
./packaging/build-windows.sh

On Haiku, build on the machine itself and select the system TLS backend — the default one has no support for that platform:

pkgman install rust_bin
cargo build --release --no-default-features --features tls-native

Back to features