How to Install the Pinguzo Agent

A lightweight agent that runs on your Linux server and ships system metrics to Pinguzo every minute.

Prerequisites

Get your Agent Key first You must create the server record in Pinguzo before installing the agent. Go to Add a Server, save the record, and copy the installation command that appears — it already contains your unique Agent Key.

Quick Install (recommended)

Paste this command on your target server, replacing YOUR_64_CHARACTER_KEY with the key from your Pinguzo dashboard:

curl -fsSL https://api.pinguzo.com/files/install-agent.sh | \
  sudo bash -s -- --agent-key=YOUR_64_CHARACTER_KEY

The installer will:

  1. Download the Pinguzo package and extract it to /usr/local/pinguzo/
  2. Write the configuration file to /usr/local/pinguzo/config/agent.conf
  3. Add a cron job that runs the agent every minute
  4. Run the agent once immediately to verify connectivity

Installation Options

The installer supports additional flags passed after --:

FlagRequiredDescription
--agent-key=KEY Yes 64-character hexadecimal key from the Pinguzo dashboard. Authenticates the agent to the edge server.
--edge=HOSTNAME No Pin the agent to a specific edge server hostname (e.g., ca.pinguzo.com, uk.pinguzo.com, in.pinguzo.com). If omitted, Pinguzo auto-selects the lowest-latency edge.

Example: Pin to a specific edge

curl -fsSL https://api.pinguzo.com/files/install-agent.sh | \
  sudo bash -s -- --agent-key=YOUR_64_CHARACTER_KEY --edge=uk.pinguzo.com
When to pin an edge If your servers are in a specific region, pin them to the nearest edge for lower latency and to keep data within a geographic boundary. If you have servers spread globally, leave this blank for automatic selection.

File Locations

PathPurpose
/usr/local/pinguzo/bin/pinguzo-agent.shMain agent script
/usr/local/pinguzo/config/agent.confConfiguration file (agent key, edge URL)
/usr/local/pinguzo/queue/Temporary queue for offline buffering
/var/log/pinguzo/agent.logAgent log file

How the Agent Works

The agent is a Bash script scheduled by cron to run every minute. Each run:

  1. Collects system metrics (see Metrics Collected below)
  2. Serializes the payload as JSON
  3. POSTs it over HTTPS to the assigned Pinguzo edge server
  4. If the POST fails (network issue), saves the payload to the local queue directory
  5. On the next run, retries any queued payloads after sending the current one
Resilient to short outages If the edge server is temporarily unreachable, the agent queues data locally and drains the queue once connectivity is restored. No data is lost during brief network interruptions.

Metrics Collected

MetricDescription
CPU Usage %Overall CPU utilization across all cores
CPU Steal %Percentage of time the hypervisor stole from your vCPU (cloud VMs only)
Memory Usage %Used RAM as a percentage of total installed RAM
Disk Usage %Highest disk usage percentage across all mounted partitions
Load Average1-minute, 5-minute, and 15-minute load averages
UptimeSystem uptime in seconds (used to detect reboots)
Process ListTop 100 processes by CPU and memory (name, PID, CPU%, RAM%)
Network InterfacesBytes/packets sent and received per interface
Disk PartitionsUsage stats per mounted filesystem
SMART HealthDisk health status if smartctl is installed (Passed / Failed)
OS InfoDistribution, kernel version, architecture (sent on first check-in)
IP AddressPrimary network interface IP (sent on first check-in)

Verifying the Installation

Check agent logs

tail -f /var/log/pinguzo/agent.log

If there is an error in sending the metrics you will see the logs here

Verify the cron job was created

cat /etc/cron.d/pinguzo

Expected output:

* * * * * /usr/local/pinguzo/bin/pinguzo-agent.sh >> /var/log/pinguzo/agent.log 2>&1

Check the Pinguzo dashboard

Navigate to Servers in Pinguzo. Within 1–2 minutes the server should show Online with OS details populated.

Troubleshooting

Agent key rejected (HTTP 401)

Double-check that the key in /usr/local/pinguzo/config/agent.conf matches the key shown in your Pinguzo dashboard. Ensure there are no leading/trailing whitespace characters. If the server was deleted and re-added, update the key in the config file.

Cannot connect to edge server (network error)

Verify outbound HTTPS is allowed from the server:

curl -v https://ca.pinguzo.com/healthz.php

If this fails, check firewall rules, security groups (if on a cloud provider), or proxy settings.

Cron not running

Ensure the cron daemon is running:

# Debian / Ubuntu
systemctl status cron

# RHEL / CentOS / Rocky
systemctl status crond

Permission errors

The agent must run as root. Check that the cron entry is in root's cron (/etc/cron.d/pinguzo), not a user cron.

Updating the Agent

To update the agent to the latest version, run the built-in update command:

/usr/local/pinguzo/bin/pinguzo-agent.sh --updates

By default, Pinguzo checks for updates and auto updates once a day.

Uninstalling the Agent

To remove the agent from a machine, run the built-in uninstall command:

/usr/local/pinguzo/bin/pinguzo-agent.sh --uninstall

This removes the cron job, agent script, config, and log files. It does not delete the server record or historical data from your Pinguzo dashboard — delete the server from the dashboard separately if needed.

Security Considerations

Next Steps