Skip to main content

Register & Install the Agent

Installation

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.
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