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