# Requirements ### Server Stack #### Operating system - Supported: Debian/Ubuntu and RHEL family (AlmaLinux, Rocky, CentOS). - Init: systemd (required — agent is designed as a systemd unit). - Architecture: Linux x86\_64 (typical VPS; agent uses standard distro package managers). #### Runtime dependencies
ComponentRequiredNotes
Python 3.9+
Yes
Stdlib only; on EL8 minimal images may need `python39`
systemd
Yes
Service: `balctl-heartbeat.service`
wget or curl
Install-time
Download `agent.zip`
unzip
Install-time
Extract bundle
sudo / root
For full feature set
Heartbeat itself can run unprivileged; most panel jobs need root
#### Optional packages (installed by agent jobs when needed)
PackageWhen
haproxy
Install HAProxy job or `BALCTL_PROVISION_HAPROXY=1`
socat
Admin socket drain/ready, runtime HAProxy commands
firewalld
RHEL-family firewall jobs (auto-installed on first “Refresh rules” if missing, agent v78+)
ufw
Debian firewall backup jobs
### Network requirements #### Outbound HTTPS (required) The VM must reach:
DestinationPurpose
`https://serversctl.com` (or your `BALCTL_API_BASE`)
Heartbeat, job claim/complete, backup upload/download
`https://download.serversctl.com/agent.zip`
Self-update (default)
`https://api.ipify.org` (optional)
Public IPv4 discovery when `BALCTL_PROBE_PUBLIC_IP=1`
All agent API traffic must use HTTPS — the agent refuses plaintext `BALCTL_API_BASE` / `BALCTL_UPDATE_URL` (v28+). #### Inbound (not required) Panel-driven operations use the outbound job queue. No inbound SSH or agent port is required if the agent runs as root for privileged jobs. #### IP allowlisting (enrollment) When you create a pool member, you must supply at least one allowed source IPv4. This is the VM’s outbound/egress IP as seen when it calls the control plane — not necessarily its SSH IP or the IP traffic should hit. The control plane validates `CF-Connecting-IP` against the enrolled allowlist on every agent request. Mismatch → 403. #### Enrollment requirements Before the agent can heartbeat, create the member in the dashboard (Add pool member):
FieldRequirement
Hostname
Must match the JSON `hostname` the agent sends (case-insensitive). Override with `BALCTL_HOSTNAME` if OS hostname differs.
Allowed source IPs
One or more IPv4 addresses (comma-separated). Must include egress IP to control plane.
Enrollment secret
48 hex characters, no hyphens. Shown once in the modal. Not the member UUID on the card.
Member template
e.g. HAProxy balancer — determines which panel commands are available.
Linux family
Debian/Ubuntu vs RHEL — affects generated install one-liner.
#### Authentication model
- Header: `Authorization: Bearer <48-char-enrollment-secret>` - Secret stored server-side as SHA-256 hash only. - 401 = wrong/unknown secret. - 403 = IP not allowlisted, or hostname mismatch, or missing `CF-Connecting-IP`.