Installing the Agent

Overview

The Pingniner agent is a small program that runs on your machine, collects metrics and posts them to Pingniner. It powers both Server and Workstation monitoring — the same agent, installed in a different mode.

The agent is open source: github.com/pingniner/agent.

Because the agent pushes data out, machines behind a firewall, on a private network or behind NAT work without any inbound rules. The only network requirement is outbound HTTPS to ingest.pingniner.com.

Requirements

• Operating system: Linux, Windows, macOS or BSD
• Architecture: x64 or ARM64
• Privileges: root / Administrator, to install the service and read system metrics
• Network: outbound HTTPS (port 443) to ingest.pingniner.com and, at install time, to github.com to download the agent

You do not need Node.js installed. The installer downloads a private Node runtime alongside the agent, so nothing on your system is modified beyond the install directory and the scheduled task.

Getting your key

1. Create a Server or Workstation monitor in Pingniner.
2. Open it and use the Agent action.
3. Copy the install command — it already contains that monitor's key.

The key is a UUID that identifies the monitor. It is the only credential the agent uses.

WARNING

Treat the key like a password. Anyone who has it can post data to that monitor. Do not paste install commands containing real keys into shared documents, tickets or chat.

Install

Linux, macOS and BSD

curl -L -s -o PingninerInstaller.sh https://github.com/pingniner/agent/releases/latest/download/PingninerInstaller.sh \
  && sudo bash PingninerInstaller.sh YOUR_KEY server

Replace YOUR_KEY with your monitor's key, and use workstation instead of server for a workstation monitor.

The installer:

• creates /opt/pingniner
• downloads a Node runtime matching your platform and architecture
• downloads the agent
• registers a cron entry
• writes its log to /tmp/pingniner.log

Windows

Run in an elevated (Run as administrator) PowerShell:

Invoke-WebRequest -Uri https://github.com/pingniner/agent/releases/latest/download/PingninerInstaller.ps1 -OutFile PingninerInstaller.ps1 -UseBasicParsing; powershell -ExecutionPolicy Bypass -File PingninerInstaller.ps1 YOUR_KEY server

Again, use workstation for a workstation monitor. Files go to C:\Program Files\Pingniner, and a scheduled task named Pingniner Agent is created, running as SYSTEM.

WARNING

The Windows install command shown on the Workstation overview page currently contains a broken download URL. Use the command above instead, or copy it from the workstation list's row action, which is correct.

How often it reports

Mode	Interval
server	Every minute
workstation	Every hour

This is set at install time by the mode argument and is not configurable from Pingniner. To change it, reinstall with the other mode — but note that a server monitor and a workstation monitor are different records, so you would be moving the machine to a different monitor.

Verifying the install

1. Wait a minute or two — an hour for a workstation.
2. Reload the monitor in Pingniner. Its status should leave Unknown, and Last seen should update.
3. The Agent panel should show the installed agent version.

If nothing arrives, see Troubleshooting.

Reinstalling

Running the installer again on a machine that already has the agent replaces the existing install. This is the supported way to move a machine to a different monitor key or to recover a broken install.

Troubleshooting

No data after several minutes

Check the installer log at /tmp/pingniner.log on Unix. It records each download step and will show a failed download or a permissions error.

"Command not found" or permission errors

The install command needs sudo on Unix and an elevated PowerShell on Windows. Without it the agent cannot register its scheduled task.

The machine has no outbound internet

The agent must reach ingest.pingniner.com on port 443. If you use an egress proxy or allowlist, add that host. There is currently no proxy configuration option in the agent.

Firewall blocking GitHub

The installer downloads from github.com. If GitHub is blocked, download the installer and the platform Node binary on another machine and place them manually, or build the agent from source.

Status shows No Data

The agent reported at some point and has now stopped. Check that the cron entry or scheduled task still exists — see Managing the Agent.

Wrong monitor is updating

You used another monitor's key. Reinstall with the correct one.

Next steps

• Managing the Agent — updating, removing and checking the schedule
• What It Collects — exactly what data leaves your machine
• Server Monitoring — triggers and metrics