Private Agents Setup Guide

Deploy monitoring agents inside your network to check internal services, databases, and APIs that aren't accessible from the public internet. Private agents use the same check types as our global geo-distributed agents.

Tip

Looking for geo-distributed monitoring of public services instead? See Agents & Geo Monitoring.

What are Private Agents

Private agents are lightweight Go binaries that you deploy on servers inside your own network. They connect outbound to the SysTeam HealthChecks API, fetch their assigned checks, execute them locally, and report results back. This lets you monitor services that are not reachable from the public internet — internal databases, APIs behind VPNs, microservices on private subnets, and more.

Private agents use the same check engine as the managed geo agents, so all check types (HTTP, TCP, ICMP, DNS, Database, Mail, etc.) work identically.

Prerequisites

Pro plan or higher on your organization
Supported platforms: Linux (amd64/arm64), macOS (amd64/arm64), Docker
Outbound HTTPS access to checks.systeam.pl (port 443)
For ICMP checks: the agent needs CAP_NET_RAW capability or root privileges
For MTR diagnostics: mtr-tiny (Debian/Ubuntu) or mtr (Alpine) installed on the host

Quick Start

Go to Organization → Agents in the sidebar
Click "Generate Token" to create a one-time registration token
Copy the install command and run it on your target server
The agent registers itself, appears in the Agents list, and starts accepting checks

Installation Methods

Option 1: curl one-liner

Install via curl

curl -sSL https://checks.systeam.pl/api/install-agent | bash -s -- --token YOUR_TOKEN

This downloads the latest agent binary for your platform, installs it to /usr/local/bin, registers with the API, and creates a systemd service.

Option 2: Docker

Docker run

docker run -d \
  --name systeam-agent \
  --restart unless-stopped \
  -e AGENT_TOKEN=YOUR_TOKEN \
  -e CENTRAL_URL=https://checks.systeam.pl \
  registry.cygal.net/healthcheck-agent:latest

Tip

For ICMP checks inside Docker, add --cap-add=NET_RAW to the run command.

Option 3: Manual installation

Download the agent binary from the Agents page or build from source
Create a config.yaml file (see Configuration below)
Run the binary: ./healthcheck-agent --config /path/to/config.yaml

Configuration

The agent can be configured via environment variables or a YAML config file. Environment variables take precedence over config file values.

config.yaml

# SysTeam HealthCheck Agent Configuration

# URL of your HealthChecks instance (required)
central_url: https://checks.systeam.pl

# Agent key received after registration (required after first run)
agent_key: your_agent_key_here

# How often to send heartbeats in seconds (default: 30)
heartbeat_interval: 30

# Maximum number of checks to run concurrently (default: 10)
max_concurrent_checks: 10

# Log level: debug, info, warn, error (default: info)
log_level: info

Configuration Reference

YAML Key	Env Variable	Description	Default
`central_url`	`HC_API_URL`	URL of your HealthChecks instance	Required
`agent_key`	`HC_AGENT_KEY`	Agent key (received after registration)	—
`heartbeat_interval`	`HC_HEARTBEAT_INTERVAL`	Heartbeat frequency in seconds	30
`max_concurrent_checks`	`HC_MAX_CONCURRENT`	Max concurrent check executions	10
`log_level`	`HC_LOG_LEVEL`	Logging verbosity	info

Assigning Checks

Once your agent is registered and online:

Create a new check or edit an existing one
In the "Execution" section, check one or more private agents to assign to this check
Save the check

The agent polls for new checks every 10 seconds. Your check will start executing on the agent within a few seconds of saving.

Tip

Multi-agent execution: You can assign multiple private agents to a single check. This is useful for monitoring the same internal service from different offices or network segments. The check status is aggregated across all assigned agents — it shows UP only when all sources are up, DEGRADED when some fail, and DOWN when all fail (or when any critical source fails).

Hybrid Execution (Private + Geo)

Private agents and geo monitoring are no longer mutually exclusive. You can enable both on the same check to run it simultaneously from your private agents and from the global geo-distributed locations. This gives you both internal visibility and external perspective from the same check.

Critical Sources

Each execution source (agent or geo location) can be marked as critical. When a critical source reports DOWN, the entire check immediately escalates to DOWN — regardless of what other sources report. This is useful when certain vantage points are non-negotiable (e.g. your primary datacenter agent).

Non-critical sources contribute to DEGRADED state when they fail, but do not on their own force the check to DOWN.

To mark a source as critical, click the ★ critical toggle next to the agent or geo location in the Execution section of the check form.

Smart Defaults

When creating a new check, the platform applies sensible defaults based on the check type:

Database checks — geo monitoring is disabled by default, since databases are rarely publicly accessible. Assign a private agent to monitor from inside your network.
HTTP/HTTPS checks — geo monitoring is enabled by default for external perspective across all 7 distributed locations.
All other check types default to central execution if no agent or geo source is selected.

Source Breakdown in Check Detail

The check detail page shows a per-source status breakdown under the Execution Sources panel. Each agent and geo location listed shows its current status (UP / DOWN / DEGRADED / UNKNOWN) along with the last result timestamp. This lets you instantly pinpoint which source is failing without digging through logs.

Monitoring Agent Health

The Agents page in the sidebar shows all registered agents with their current status:

Online — Heartbeat received within last 90 seconds

Offline — No heartbeat for over 90 seconds

Agents send heartbeats every 30 seconds. If no heartbeat is received for 5 minutes, the agent is considered offline and an SSE event (agent.status) is published for real-time UI updates.

Supported Check Types

Private agents support all check types available on the platform:

HTTP/HTTPS — Full support including headers, body, content matching, SSL certificate info, form login
TCP — Port connectivity, response time, banner grab
ICMP — Ping with packet loss, min/avg/max RTT
UDP — UDP service availability
DNS — Record resolution with multi-server iteration
FTP — FTP/SFTP server connectivity
Database — PostgreSQL, MySQL, MongoDB, Redis connectivity and query
Mail Server — SMTP/IMAP/POP3 connectivity checks. Note: when a private agent is assigned, it handles only the connectivity layer. SPF/DKIM/DMARC/RBL/PTR checks always run centrally, piggybacked on the agent results.

Warning

Database checks and public accessibility: If you run a database check from the central server or geo agents, the database must be reachable from those IPs. For databases behind a firewall or VPN, always assign a private agent inside the same network.

Troubleshooting

Agent won't register

Token expired or already used — Registration tokens are single-use. Generate a new token from the Agents page.
Network connectivity — Ensure the server can reach checks.systeam.pl on port 443. Test with curl -I https://checks.systeam.pl/api/health.
Proxy or firewall — If behind a corporate proxy, set HTTPS_PROXY environment variable.

Agent shows Offline

Service stopped — Check if the agent process is running: systemctl status healthcheck-agent or docker ps.
Firewall blocking outbound — The agent needs outbound HTTPS (443) to the API server.
DNS resolution — Verify the agent host can resolve checks.systeam.pl.

Check not running on agent

Check not assigned — Verify the check has the correct agent selected in the Execution section of the check settings.
Check is paused — Paused checks are not sent to agents.
Agent key mismatch — If the agent was re-registered, the old key is invalid. Use the new key from registration.

Security

Treat your agent key like a password. Anyone with the key can submit check results to your account. Store it in environment variables or a secrets manager, not in plain text files accessible to other users.