Reference for what the installer changes on your host, where to look when something goes wrong, and how re-enrollment works. If you just want an agent running, Getting started is shorter.
amd64 or arm64 on Linux and macOS. amd64 (64-bit x86) on Windows.sudo or a root shell. On Windows, a PowerShell window opened with Run as Administrator.curl and tar on Linux and macOS, preinstalled on most systems. Nothing extra on Windows: the built-in Windows PowerShell 5.1 is enough.api.hyperping.io and ingest.hyperping.io.Replace the placeholder with the install token from the dashboard:
curl -fsSL https://hyperping.com/install.sh | sh -s HP_INSTALL_xxxxxThe script is POSIX sh, so sh, dash, and bash all work. If your pipeline forces a particular shell, pipe to that shell explicitly, for example ... | bash -s HP_INSTALL_xxxxx.
On Windows the installer is a PowerShell script, install.ps1. Open PowerShell with Run as Administrator and run:
& ([scriptblock]::Create((irm https://hyperping.com/install.ps1))) HP_INSTALL_xxxxxThe [scriptblock]::Create(...) form is what lets you pass the token and flags as arguments. The dashboard's Windows tab, next to Linux / macOS above the install command, gives you this command with your token already filled in.
[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072
& ([scriptblock]::Create((irm https://hyperping.com/install.ps1))) HP_INSTALL_xxxxxPass flags after the install token to set a display name, bind an escalation policy, or drop the server into a group on first enrollment. Useful when you're running the same command across an Ansible inventory, a Terraform remote-exec, or a Kubernetes DaemonSet.
curl -fsSL https://hyperping.com/install.sh | sh -s -- \
HP_INSTALL_xxxxx \
--name "web-01" \
--policy 6fe4c2e0-... \
--group web-tier--name--policy--group--forceEvery flag is also readable from an environment variable, which is cleaner for config-management tools that export variables rather than template long command lines:
HP_DISPLAY_NAME="web-01" HP_POLICY_UUID=6fe4c2e0-... HP_GROUP_NAME=web-tier \
sh -c "$(curl -fsSL https://hyperping.com/install.sh)" -- HP_INSTALL_xxxxxThe mapping is --name → HP_DISPLAY_NAME, --policy → HP_POLICY_UUID, --group → HP_GROUP_NAME. Explicit flags win over environment variables when both are set.
On Windows the same options are PowerShell parameters: -Name, -Policy, -Group, -Force, plus -Interval for the collection interval in seconds (default and minimum 30). The installer reads the same environment variables, and $env:HP_INSTALL_TOKEN can stand in for the token argument.
& ([scriptblock]::Create((irm https://hyperping.com/install.ps1))) HP_INSTALL_xxxxx `
-Name "web-01" `
-Policy 6fe4c2e0-... `
-Group web-tierEvery project has one stable install token, which is what the dashboard shows by default. Beyond that you can mint bound install tokens from the Advanced link next to the install command. A bound token carries its own default name, policy, and group, so the one-liner stays short even when the fleet has a specific destination in mind.
default_display_name, default_policy_uuid, and default_group_name. Good for fleets where every host in a group shares the same destination.Resolution order when a server enrolls: explicit flag, then bound token default, then existing value on the server row. This is why a bound token's defaults can be overridden on specific hosts without losing them on the rest.
Identifies OS (linux or macos), architecture, and init system (systemd or launchd). On Windows, install.ps1 checks that it runs as Administrator on Windows 10 / Server 2016 or later, 64-bit, with at least 200 MB free on the system drive.
Fetches hp-agent-<version>-<os>-<arch>.tar.gz (hp-agent-<version>-windows-amd64.zip on Windows) from api.hyperping.io/downloads/agent and checks its SHA256.
Exchanges the install token for a per-host agent token, writes config under /etc/hyperping/ (C:\ProgramData\Hyperping on Windows), and starts the service. The first scrape reaches Hyperping within a few seconds.
/usr/local/bin/hp-agent/usr/local/libexec/ (collector and sidecar binaries)/etc/hyperping/agent.env and /etc/hyperping/agent.yaml/var/lib/hyperping//var/log/hyperping//etc/systemd/system/hp-agent.service/Library/LaunchDaemons/com.hyperping.agent.plistOn Windows:
C:\Program Files\Hyperping\hp-agent.exeC:\ProgramData\Hyperping\agent.yaml. It holds the agent token, so the folder is readable by SYSTEM and Administrators only.C:\ProgramData\Hyperping\queuehp-agent Windows service, started automatically at boot and restarted 5 seconds after a crash.hp-agent-watchdog scheduled task, run as SYSTEM every 5 minutes and at boot. It runs C:\Program Files\Hyperping\hp-agent-watchdog.ps1, which restarts the service when it still shows Running but has stopped collecting or sending metrics for 10 minutes. When only the disk, filesystem, or paging metrics are frozen, which doesn't take the server offline, it waits 60 minutes instead. In both cases it waits at least three collection intervals. It also restarts a service that has been stuck starting (StartPending) for more than 5 minutes, or 60 minutes while its CPU and memory metrics still come in, which means only a disk, filesystem, or paging collector is blocked. It restarts at most once every 30 minutes, and waits longer between attempts, up to 4 hours, while restarts don't bring the metrics back. Each restart is written to the Application event log, source hp-agent: event 7001 (warning) when it worked, 7002 (error) when it failed, with the reason in the message.hp-agent.Service status on Linux:
sudo systemctl status hp-agent.serviceTail logs on Linux:
sudo journalctl -u hp-agent.service -fService status on macOS:
sudo launchctl print system/com.hyperping.agentLogs are also written under /var/log/hyperping/.
Service status on Windows:
Get-Service hp-agentRecent logs on Windows, from the Application event log:
Get-WinEvent -ProviderName hp-agent -MaxEvents 20There is no dedicated heartbeat: liveness is derived from metric arrival. The dashboard reflects four states:
--uninstall on the host. The row is kept for ownership history; no alerts.Three separate actions are available from the server's menu. Pick the one that matches what you're trying to do:
sh -s -- --uninstall on Linux and macOS, -Uninstall on Windows. Run it on the host to stop the service and remove binaries. See Uninstall.Cloud resource detection (EC2, GCE, Azure) is off by default to keep cold-start latency low on bare-metal hosts. On cloud VMs where you want the instance metadata shown alongside host info, enable the relevant detector in /etc/hyperping/agent.yaml and restart the agent (systemctl restart hp-agent on Linux, launchctl kickstart -k system/com.hyperping.agent on macOS). On Windows the file is C:\ProgramData\Hyperping\agent.yaml and the restart is Restart-Service hp-agent.
Re-running the installer on a host that has already enrolled keeps the same server UUID and its metric history, rotates the per-host agent token, and revokes the old one. Safe to use for credential rotation or recovery from a compromised agent.env.
On re-enrollment, display name, escalation policy, and group are sticky: the installer will only fill them if the server row has no value yet. This protects edits you've made in the dashboard from being overwritten by a pipeline that re-runs the installer. Pass --force when you do want the installer to win.
curl -fsSL https://hyperping.com/install.sh | sh -s -- HP_INSTALL_xxxxx --name "web-prod-01" --forceHostname, OS, architecture, and agent version always update from whatever the host reports. Those are facts about the machine, not user-editable preferences, so they don't need the --force gate.
To update the agent, run the install command again on the host, on Linux, macOS, and Windows alike. The installer downloads the current release, replaces the binary and the configuration in place, and restarts the service. The server keeps its UUID, its metric history, and its alert settings.
curl -fsSL https://hyperping.com/install.sh | sh -s HP_INSTALL_xxxxx& ([scriptblock]::Create((irm https://hyperping.com/install.ps1))) HP_INSTALL_xxxxx--force (-Force on Windows) only when you want to overwrite them./var/lib/hyperping/queue, C:\ProgramData\Hyperping\queue on Windows). Metrics waiting to be sent are sent after the restart.agent.yaml (and agent.env on Linux and macOS) is overwritten with the installer's version, so hand edits such as an enabled cloud detector are lost: apply them again afterwards. On Windows the watchdog script and its scheduled task are reinstalled too.--interval (-Interval on Windows) or set HYPERPING_INTERVAL again.The tarball failed integrity check. Usually a dropped connection or a rewriting proxy. Re-run the command. If it fails again, confirm api.hyperping.io is reachable and not behind a transforming proxy.
Check outbound HTTPS to ingest.hyperping.io. Tail the logs and look for TLS or DNS errors. A blocked egress firewall is the most common cause.
The installer needs curl and tar. Install them through your package manager and re-run.
If enrollment fails with 401 token_revoked or token_expired, the token has been revoked or has aged out. Generate a fresh one from the Servers view, or open Advanced to mint a bound token.
The --policy UUID doesn't belong to this project. Copy the UUID directly from the policy detail page in the dashboard, and double-check you're using the right install token for the project you expect.
The installer registers a Windows service and writes under C:\Program Files, so it needs an elevated session. Right-click PowerShell, pick Run as Administrator, and run the command again.
Windows PowerShell 5.1 on Server 2016 negotiates TLS 1.0 by default, which Hyperping does not accept. Run [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072 in the same window first, or copy the command from the dashboard, which includes that line.
The service started but the collector exited right after. Read the reason with Get-WinEvent -ProviderName hp-agent -MaxEvents 20. After editing agent.yaml by hand, restart with Restart-Service hp-agent.
Backup software that relies on Volume Shadow Copy (Microsoft Azure Backup Server and DPM, Veeam, and others) mounts and dismounts volumes while a backup runs. A Windows disk call made by the agent could hang on one of those volumes, and because every metric was collected in the same cycle, all of them stopped: the server went Offline while Get-Service hp-agent still showed Running, and restarting the service brought it back.
This is fixed from the installer published on November 4, 2026. Disk, filesystem, and paging metrics are now collected separately with a 10-second timeout, so a stuck disk call pauses only the disk metrics. Disk space is read only for drives with a letter, which backups don't mount and dismount. If the agent freezes anyway, the hp-agent-watchdog task restarts it: after 60 minutes when only the disk, filesystem, or paging metrics are stuck, since the server stays online meanwhile, and after 10 minutes otherwise. A disk call blocked by a backup can also hold the agent's start, because the service only shows Running once every collector has started: the watchdog restarts a service stuck starting for more than 5 minutes, or for more than 60 minutes while its CPU and memory metrics still come in. A stop that hangs is ended after 30 seconds.
Agents installed before that date don't get the fix on their own: run the installer again on each server, outside a backup window if you can. If a backup blocks the start during the update, the installer stops waiting after 90 seconds and exits with an error that says so; the watchdog task is already back in place and restarts the agent 5 to 10 minutes after that start, or within the hour when only the disk, filesystem, or paging collector is blocked. The agent version stays 0.2.0, so check for the watchdog task instead; if it exists, the host runs the new installer:
Get-ScheduledTask hp-agent-watchdogDon't raise the priority of hp-agent.exe to Realtime. The agent isn't short of CPU, it waits on Windows, so a higher priority doesn't help, and a Realtime process can starve the rest of the server, the backup included. If a tool keeps that setting across restarts, set it back to Normal.
Each watchdog restart is logged in the Application event log as event 7001 (restart done) or 7002 (restart failed), with the reason. List them with:
Get-WinEvent -FilterHashtable @{ LogName = 'Application'; ProviderName = 'hp-agent'; Id = 7001, 7002 } -MaxEvents 20 |
Format-List TimeCreated, Id, Message"No events were found that match the specified selection criteria" means the watchdog hasn't had to restart the agent. If you see a restart during every backup, send us the text of a 7001 event.
You ran the Linux / macOS command from Git Bash, MSYS2, or Cygwin. The agent runs as a native Windows service, so use the PowerShell installer from an Administrator PowerShell window instead.
On re-enrollment, display name, policy, and group are sticky by design: the installer won't overwrite a value that's already set. Add --force when you want the installer to win over a UI edit.