Skip to content
statance
MenuClose

Agent

Install the Statance agent on Linux, macOS, Windows, Docker and Kubernetes. What it collects and how it reports.

The Statance agent collects host metrics every 60 seconds and sends them over HTTPS to api.statance.com. On Linux and macOS it is a single bash script that needs only bash and curl; on Windows it is a PowerShell script.

Linux & macOS

curl -fsSL https://statance.com/install.sh | sudo bash -s -- YOUR_API_KEY

The installer:

  • installs the agent to /opt/statance-agent;
  • writes its config to /etc/statance-agent (your API key plus a per-server token generated on the host);
  • creates a statance-agent systemd service on Linux, or a launchd daemon on macOS.

Re-running the installer upgrades the agent in place and keeps the existing server token, so the server keeps its history.

# Status and logs (Linux)
systemctl status statance-agent
journalctl -u statance-agent -f

# Uninstall (Linux)
sudo systemctl disable --now statance-agent
sudo rm -rf /opt/statance-agent /etc/statance-agent /etc/systemd/system/statance-agent.service

Windows

In PowerShell running as Administrator:

iwr -useb https://statance.com/install.ps1 | iex; Install-Statance -Key YOUR_API_KEY

The agent runs as a scheduled task under SYSTEM and starts at boot.

On Windows the agent reports CPU, memory, disks, network and top processes. The deeper metrics below (per-device disk I/O, TCP states, listening ports, services, updates, containers, GPU) and the software inventory used for security checks are Linux-only; macOS reports the basic set. HTTP proxies are not supported on Windows yet.

Docker

docker run -d --name statance-agent --restart unless-stopped --pid host --network host --uts host \ -v /proc:/host/proc:ro -v /sys:/host/sys:ro -v /:/host/root:ro -v /var/run/docker.sock:/var/run/docker.sock:ro \ -e STATANCE_KEY=YOUR_API_KEY alpine:3.20 sh -c "wget -qO- https://statance.com/agent/container.sh | sh"

The read-only host mounts, --pid host and --uts host let the agent report the host’s metrics, processes and hostname rather than its own container’s; the read-only Docker socket mount enables per-container stats.

Kubernetes

kubectl create namespace statance && kubectl -n statance create secret generic statance --from-literal=key=YOUR_API_KEY
kubectl apply -f https://statance.com/agent/kubernetes.yaml

This creates a DaemonSet so every node, including nodes added later, reports in.

What is collected

On Linux the agent collects everything below every 60 seconds (security inventory every 6 hours); macOS and Windows report CPU, memory, disks, network and top processes. Host details — hostname, OS, distribution, release, kernel, architecture, CPU model, cores, total memory and uptime — are sent with each report.

GroupMetrics
CPUTotal and breakdown: user, system, iowait, steal, irq; Context switches and interrupts per second; Load average 1 / 5 / 15; CPU temperature
MemoryUsed, available, cached and buffers; Swap used and total
DisksSpace and inodes per filesystem; Per-device I/O: read/write throughput, IOPS, utilisation %
NetworkThroughput per interface; Packets per second, errors and drops; TCP connection states
SystemProcesses, threads and zombies; Open file descriptors; Logged-in users; Listening ports with owning process; Failed systemd services
UpdatesPending package updates and security updates; Reboot required
Containers & GPUDocker containers: status, CPU, memory and network per container; NVIDIA GPU utilisation, memory and temperature (if nvidia-smi exists)
ProcessesTop processes by CPU and memory
Security (every 6 hours)Security-relevant software versions and distro packages for CVE, CISA KEV and end-of-life checks

Docker metrics appear on hosts running Docker, and GPU metrics only when nvidia-smi is installed. See Security monitoring for the security inventory.

Ingest endpoint

The agent posts one JSON document per minute. You can use the same endpoint to report from custom tooling:

POST /v1/ingest

curl -X POST https://api.statance.com/v1/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "token": "unique-per-server-token",
    "version": "1.0.0",
    "host":    { "hostname": "web-1", "os": "linux", "distro": "Ubuntu", "release": "24.04",
                 "kernel": "6.8.0", "arch": "x86_64", "cpuModel": "AMD EPYC", "cores": 4,
                 "totalMemory": 8589934592, "uptime": 86400 },
    "cpu":     { "load": 23.5, "load1": 0.8, "load5": 0.6, "load15": 0.5, "temp": 48 },
    "memory":  { "total": 8589934592, "used": 4294967296, "available": 4294967296,
                 "swapTotal": 0, "swapUsed": 0 },
    "disks":   [{ "mount": "/", "fs": "ext4", "size": 85899345920, "used": 34359738368 }],
    "network": [{ "iface": "eth0", "rx_sec": 12000, "tx_sec": 3400 }],
    "processes": [{ "pid": 1234, "name": "nginx", "user": "www-data", "pcpu": 3.2, "pmem": 1.1 }]
  }'

The first report with a new token registers the server (subject to your plan’s server limit). Sizes are bytes; network rates are bytes per second.

Firewalls and proxies

The agent needs outbound TCP 443 to api.statance.com. To use a proxy on Linux, add it to the service environment:

sudo systemctl edit statance-agent
# add:
[Service]
Environment=HTTPS_PROXY=http://proxy:3128

sudo systemctl restart statance-agent

Proxies are not supported by the Windows agent yet.

Original Statance agents

Agents installed with the original Node.js installer keep working against the legacy API. To upgrade, re-run the installer above; your server keeps its identity.

Next: Monitors →