Skip to main content

Register & Install the Agent

Installation

When adding a member to a pool, you will be asked whether the server is an HAProxy node. 

Only select HAProxy Server if the server is currently running, or will be running, HAProxy.

For all other server types—including cPanel, OpenLiteSpeed, Galera, database servers, and general-purpose Linux hosts—select Generic Linux.

Choosing the correct template ensures that ServersCTL enables the appropriate features and management tools for that server. If you accidentally select the wrong template, remove the member from the pool and add it again using the correct template.

Recommended: one-shot from the dashboard

  1. Register an account at https://serversctl.com/app/
  2. Add a new pool. https://serversctl.com/app/sites
    • Servers can be pooled together. For example, cPanel Servers, LiteSpeed. ur ServersCTL.com account can hold very
  3. Select Add Member. The modal generates a paste-ready command that:
    • Ensures unzip + python3 (via apt or dnf/yum).
    • Downloads https://download.serversctl.com/agent.zip.
    • Runs balctl-agent.sh --enrol --key … --hostname … --api-base ….
    • Writes /etc/balctl/agent.env, runs --update, enables systemd.
  4. The ServersCTL UI will now start to report agent information.
    • See troubleshooting if you have problems.

Files after install

Path Role
/usr/local/bin/balctl_heartbeat.py
Agent binary
/etc/systemd/system/balctl-heartbeat.service
systemd unit
/etc/balctl/agent.env
Secrets + config (chmod 600)
/var/lib/balctl/
State stamps (e.g. .haproxy-provisioned)

Bundle contents (agent.zip)

Flat zip: balctl_heartbeat.py, balctl-agent.sh, balctl-heartbeat.env.example, balctl-heartbeat.service, README.md, LICENSE, INSTALL_VM.txt.

Configuration (/etc/balctl/agent.env)

If your configured hostname is different from the hostname sent to ServersCTL, use BALCTL_HOSTNAME

Variable Required Default Purpose
BALCTL_ENROLLMENT_SECRET
Yes (heartbeat)
—
48 hex chars from modal
BALCTL_API_BASE
No
https://serversctl.com
Control plane origin
BALCTL_INTERVAL_SEC
No
1
Bootstrap interval only; control plane returns authoritative heartbeatIntervalSec (1–60s)
BALCTL_HOSTNAME
No
OS hostname/FQDN
Override reported hostname
BALCTL_DECLARE_IP
No
—
Fixed IPv4 in heartbeat JSON (for DNS failover)
BALCTL_PROBE_PUBLIC_IP
No
off
Discover public IPv4 via HTTPS each heartbeat
BALCTL_PUBLIC_IP_URL
No
https://api.ipify.org
Probe URL
BALCTL_UPDATE_URL
No
https://download.serversctl.com/agent.zip
Self-update zip
BALCTL_PROVISION_HAPROXY
No
off
One-shot HAProxy install on first start (root)
BALCTL_ALLOW_AGENT_DOWNGRADE
No
off
Allow installing older agent from zip (not recommended)

Systemd loads this via EnvironmentFile=/etc/balctl/agent.env. Manual sudo python3 … runs merge missing vars from the same file.

Back to top