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.sudo or a root shell.curl and tar available on the host. Preinstalled on most systems.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.
Pass 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.
Every 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).
Fetches hp-agent-<version>-<os>-<arch>.tar.gz 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/, 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.plistService 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/.
There 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 one-liner to your clipboard. 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).
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.
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.