Install the agent

Updated April 19, 2026

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.

Requirements

Linux with systemd, or macOS with launchd.

Architecture

amd64 or arm64.

Privileges

Root access via sudo or a root shell.

Tools

curl and tar available on the host. Preinstalled on most systems.

Egress

Outbound HTTPS to api.hyperping.io and ingest.hyperping.io.

Install command

Replace the placeholder with the install token from the dashboard:

TerminalBASH

curl -fsSL https://hyperping.com/install.sh | sh -s HP_INSTALL_xxxxx

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

Install-time overrides

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.

TerminalBASH

curl -fsSL https://hyperping.com/install.sh | sh -s -- \
  HP_INSTALL_xxxxx \
  --name "web-01" \
  --policy 6fe4c2e0-... \
  --group web-tier

--name

Friendly display name shown in the dashboard. Falls back to the host's own hostname when not set.

--policy

Escalation policy UUID to attach. Copy it from the policy detail page in the dashboard.

--group

Group to land the server in. The group is created on demand if it doesn't exist.

--force

Overwrite name, policy, and group on re-enrollment of a host that already exists. See Re-enrollment.

Every flag is also readable from an environment variable, which is cleaner for config-management tools that export variables rather than template long command lines:

Environment variablesBASH

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_xxxxx

The mapping is --name → HP_DISPLAY_NAME, --policy → HP_POLICY_UUID, --group → HP_GROUP_NAME. Explicit flags win over environment variables when both are set.

Install tokens and bound defaults

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.

Stable project token

Always available. Safe to paste into ad-hoc installs or docs. Override defaults with flags when you need to.

Bound install token

Carries default_display_name, default_policy_uuid, and default_group_name. Good for fleets where every host in a group shares the same destination.

Plaintext visibility

The token is shown once, at creation. Reopening Advanced only surfaces a short ID. Lose it, revoke and mint a new one.

Revocation

Revoking a token blocks further enrollments through it. Agents that enrolled earlier keep running on their own per-host agent tokens.

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.

What the installer does

Step 01

Detect the host

Identifies OS (linux or macos), architecture, and init system (systemd or launchd).

Step 02

Download and verify

Fetches hp-agent-<version>-<os>-<arch>.tar.gz from api.hyperping.io/downloads/agent and checks its SHA256.

Step 03

Enroll and register

POSTs the install token to /v1/ingest/enroll, writes config under /etc/hyperping/, and starts the service. First heartbeat within seconds.

Where files are written

Binary

/usr/local/bin/hp-agent

Libexec

/usr/local/libexec/ (collector and sidecar binaries)

Config

/etc/hyperping/agent.env and /etc/hyperping/agent.yaml

State

/var/lib/hyperping/

Logs

/var/log/hyperping/

Linux service

/etc/systemd/system/hp-agent.service

macOS service

/Library/LaunchDaemons/com.hyperping.agent.plist

Checking the agent

Service status on Linux:

LinuxBASH

sudo systemctl status hp-agent.service

Tail logs on Linux:

LinuxBASH

sudo journalctl -u hp-agent.service -f

Service status on macOS:

macOSBASH

sudo launchctl print system/com.hyperping.agent

Logs are also written under /var/log/hyperping/.

Re-enrollment and token rotation

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.

TerminalBASH

curl -fsSL https://hyperping.com/install.sh | sh -s -- HP_INSTALL_xxxxx --name "web-prod-01" --force

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

Sticky fields at a glance

On first enrollment, flags or bound-token defaults populate the row. On re-enrollment without --force, only empty columns get filled. With --force, the resolved values overwrite whatever is there.

Troubleshooting

Common issues 4 scenarios

SHA256 mismatchdownload

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.

Service starts, no metricsnetwork

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.

Required command not foundtooling

The installer needs curl and tar. Install them through your package manager and re-run.

Install token revoked or expiredauth

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.

escalation_policy_not_found on enrollmentconfig

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.

Name or policy didn't updatesticky-fields

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.

← Getting started Metrics collected →