Skip to main content

Uninstall The Agent

Fully remove the ServersCTL agent

Use this runbook when a server must stop heartbeating to ServersCTL/BalCTL and all local agent files should be removed before re-enrolling, moving between staging and production, or retiring the host.

The uninstall removes:

  • balctl-heartbeat.service
  • /etc/balctl/agent.env and local discovered credential cache
  • /usr/local/bin/balctl_heartbeat.py
  • local agent state under /var/lib/balctl
  • local agent logs and temporary installer files when present

It does not remove customer workloads or platform software such as cPanel, OpenLiteSpeed, HAProxy, MariaDB/MySQL, Nginx, firewalld, CSF, websites, databases, DNS zones, or backup archives outside /var/lib/balctl.

Before removing the agent, delete or disable the matching member in the panel if the server is not being re-enrolled. That revokes the old enrollment path and stops the UI from expecting more heartbeats from this host.

Debian and Ubuntu

Run as root, or paste as a user with sudo access:

sudo systemctl stop balctl-heartbeat.service 2>/dev/null || true
sudo systemctl disable balctl-heartbeat.service 2>/dev/null || true
sudo systemctl stop balctl-agent-post-update.service 2>/dev/null || true
sudo systemctl reset-failed balctl-heartbeat.service balctl-agent-post-update.service 2>/dev/null || true

sudo rm -f /etc/systemd/system/balctl-heartbeat.service
sudo rm -f /etc/systemd/system/balctl-agent-post-update.service
sudo systemctl daemon-reload

sudo rm -f /usr/local/bin/balctl_heartbeat.py
sudo rm -f /usr/local/bin/balctl-agent.sh
sudo rm -rf /etc/balctl
sudo rm -rf /var/lib/balctl
sudo rm -rf /var/log/balctl
sudo rm -rf /tmp/balctl-* /tmp/balctl_agent_* /tmp/balctl-storage-deploy

If the original installer was extracted in the current directory, remove the extracted bundle too:

rm -f agent.zip balctl-agent.sh balctl_heartbeat.py balctl-heartbeat.service balctl-agent-version.txt
rm -rf systemd

Verify removal:

systemctl status balctl-heartbeat.service --no-pager
systemctl list-unit-files | grep -i balctl || true
pgrep -af balctl_heartbeat || true
test ! -e /etc/balctl/agent.env && echo "agent.env removed"
test ! -d /var/lib/balctl && echo "agent state removed"

Expected result: balctl-heartbeat.service is not found or inactive, no balctl_heartbeat.py process is listed, /etc/balctl/agent.env is gone, and /var/lib/balctl is gone.

Do not remove python3, unzip, wget, or curl unless you are certain they were installed only for the agent. They are common system tools and may be required by the OS or other services.

RHEL, AlmaLinux, Rocky Linux, and CentOS

Run as root, or paste as a user with sudo access:

sudo systemctl stop balctl-heartbeat.service 2>/dev/null || true
sudo systemctl disable balctl-heartbeat.service 2>/dev/null || true
sudo systemctl stop balctl-agent-post-update.service 2>/dev/null || true
sudo systemctl reset-failed balctl-heartbeat.service balctl-agent-post-update.service 2>/dev/null || true

sudo rm -f /etc/systemd/system/balctl-heartbeat.service
sudo rm -f /etc/systemd/system/balctl-agent-post-update.service
sudo systemctl daemon-reload

sudo rm -f /usr/local/bin/balctl_heartbeat.py
sudo rm -f /usr/local/bin/balctl-agent.sh
sudo rm -rf /etc/balctl
sudo rm -rf /var/lib/balctl
sudo rm -rf /var/log/balctl
sudo rm -rf /tmp/balctl-* /tmp/balctl_agent_* /tmp/balctl-storage-deploy

If the original installer was extracted in the current directory, remove the extracted bundle too:

rm -f agent.zip balctl-agent.sh balctl_heartbeat.py balctl-heartbeat.service balctl-agent-version.txt
rm -rf systemd

Verify removal:

systemctl status balctl-heartbeat.service --no-pager
systemctl list-unit-files | grep -i balctl || true
pgrep -af balctl_heartbeat || true
test ! -e /etc/balctl/agent.env && echo "agent.env removed"
test ! -d /var/lib/balctl && echo "agent state removed"

Expected result: balctl-heartbeat.service is not found or inactive, no balctl_heartbeat.py process is listed, /etc/balctl/agent.env is gone, and /var/lib/balctl is gone.

Do not remove python3, python39, unzip, wget, or curl Unless you are certain they were installed only for the agent. RHEL-family systems often rely on Python packages for operating system tooling.

Re-enrol after removal

After a full removal, use the current install command from the panel. Do not reuse an old command or old enrollment secret.

Production enrollments should point at:

  • API base: https://serversctl.com
  • Agent zip: https://serversctl.com/agent/production/agent.zip

Staging enrollments should point at:

  • API base: https://staging.serversctl.com
  • Agent zip: https://staging.serversctl.com/api/agent-assets/development/agent.zip

The hostname in the command must match the panel member hostname, and the server's egress IP must be in that member's allowed source IP list.

Back to top