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 Syschecks 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 syschecks.com (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

No hosted one-line installer yet

There is currently no hosted curl | bash installer script. Download or build the healthcheck-agent binary and use its register / run subcommands below — this is the same method used for our own managed geo agents.

Option 1: Register, then run

Step 1: register (writes config.yaml with your agent key)

./healthcheck-agent register \
  -url https://syschecks.com \
  -token YOUR_REGISTRATION_TOKEN \
  -name my-private-agent \
  -config config.yaml

Step 2: run

./healthcheck-agent run -config config.yaml

register exchanges your one-time registration token for a permanent agent key and writes it to the config file. run loads that file and starts polling for checks.

Option 2: Docker

Docker run

docker run -d \
  --name systeam-agent \
  --restart unless-stopped \
  -v $(pwd)/config.yaml:/config.yaml:ro \
  registry.cygal.net/healthcheck-agent:latest run -config /config.yaml

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
Run ./healthcheck-agent register ... as shown above to create config.yaml
Run the binary: ./healthcheck-agent run -config /path/to/config.yaml

Configuration

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

config.yaml

# SysTeam HealthCheck Agent Configuration

# URL of your Syschecks instance (required)
central_url: https://syschecks.com

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

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

# How often to poll for new/changed checks in seconds (default: 60)
check_fetch_interval: 60

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

# Default per-check timeout in seconds (default: 30)
default_check_timeout: 30

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

Configuration Reference

YAML Key	Env Variable	Description	Default
`central_url`	`AGENT_CENTRAL_URL` (or `CENTRAL_URL`)	URL of your Syschecks instance	Required
`agent_key`	`AGENT_KEY`	Agent key (received after registration)	Required
`heartbeat_interval`	`AGENT_HEARTBEAT_INTERVAL`	Heartbeat frequency in seconds	30
`check_fetch_interval`	`AGENT_CHECK_FETCH_INTERVAL`	How often the agent polls for assigned checks, in seconds	60
`max_concurrent_checks`	`AGENT_MAX_CONCURRENT`	Max concurrent check executions	10
`default_check_timeout`	`AGENT_CHECK_TIMEOUT`	Default per-check timeout in seconds	30
`log_level`	`AGENT_LOG_LEVEL`	Logging verbosity	info
`log_file`	`AGENT_LOG_FILE`	Log to a file instead of stdout	—

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 or changed checks every 60 seconds by default (check_fetch_interval). Your check will start executing on the agent shortly after 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 10 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.

Reliability & False-Alarm Protection

Agents include several safeguards so brief network blips don't create incidents:

Automatic retry — Transient network errors (timeouts, connection resets, DNS hiccups) are retried once after a short delay before a failure is reported.
Two-sample confirmation — A source's status flips only after two consecutive failed samples, unless multiple sources fail at once (real outages are still detected within one polling cycle).
Connectivity self-check — Before reporting failures, the agent verifies its own network connectivity. If the agent's own network is down, its failure results are discarded instead of producing false alarms; the source shows as UNKNOWN (no data) until the agent recovers.
Silent agents go UNKNOWN — If an agent stops reporting, its source turns UNKNOWN instead of keeping the last reported state. UNKNOWN sources don't affect the check's overall status.

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 syschecks.com on port 443. Test with curl -I https://syschecks.com/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 syschecks.com.

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.