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