Agent cleanup and removal
Use this article when you need to remove a TvRMM agent from an endpoint, clean up a duplicate install, remove an agent that no longer checks in, or prepare an endpoint for a clean reinstall.
TvRMM production cleanup tools are served from:
https://portal.tvrmm.app/installers
Pick the right removal path
| Situation | What to do |
|---|---|
| The endpoint is online and visible in your tenant | Remove or retire it from the portal first. TvRMM can queue the normal uninstall workflow and preserve the endpoint history. |
| The endpoint is offline or cannot receive commands | Run the local cleanup script on the endpoint. List what it finds, dry-run the selected removal, then remove only the intended agent. |
| The endpoint has duplicate agents or the wrong tenant attached | Use the local cleanup script to list all local agents and remove the stale or incorrect one. |
| The machine was reimaged, wiped, or destroyed | No local cleanup is possible. Remove or retire the endpoint from the portal so inventory and billing state match reality. |
| You are reinstalling the agent | Remove the old local agent first, then generate a fresh bootstrap command from the production portal. |
| The portal row is an inventory-only VM or container | Do not run cleanup inside the guest unless a real in-guest TvRMM agent was installed there. Inventory-only rows are records reported by a host, not installed agents. |
Always list and dry-run before removing anything. Do not manually delete broad system directories unless TvRMM support has specifically asked you to do so.
Download the cleanup tools
Windows
Run PowerShell as Administrator:
$InstallerBase = "https://portal.tvrmm.app/installers"
Invoke-WebRequest "$InstallerBase/cleanup-agent-windows.ps1" -OutFile cleanup-agent-windows.ps1
Invoke-WebRequest "$InstallerBase/cleanup-agent-windows.cmd" -OutFile cleanup-agent-windows.cmd
The .cmd file is optional. It is only a wrapper for environments where launching from CMD is easier than launching PowerShell directly.
macOS, Linux, BSD, NAS, firewall, and homelab hosts
Run from a root-capable shell on the endpoint:
INSTALLER_BASE="https://portal.tvrmm.app/installers"
curl -fsSLO "${INSTALLER_BASE}/cleanup-agent-unix.sh"
chmod +x cleanup-agent-unix.sh
Use this same Unix cleanup script for macOS, ordinary Linux hosts, FreeBSD-based systems, NAS appliances, firewall appliances, Proxmox VE hosts, Unraid hosts, and other supported Unix-like endpoints.
List before removing
Windows:
.\cleanup-agent-windows.ps1 -List
Unix-like systems:
sudo sh cleanup-agent-unix.sh --list
The list output helps identify which local agent is installed, whether more than one agent exists, which TvRMM URL it points to, and whether the script can reach that URL.
If TvRMM support asks for structured output, use JSON:
.\cleanup-agent-windows.ps1 -List -Json
sudo sh cleanup-agent-unix.sh --list --json
Remove one selected agent
Use this when the list shows more than one local agent or when you want to remove only one known stale instance.
Windows:
.\cleanup-agent-windows.ps1 -Select 1 -DryRun
.\cleanup-agent-windows.ps1 -Select 1 -Yes
Unix-like systems:
sudo sh cleanup-agent-unix.sh --select 1 --dry-run
sudo sh cleanup-agent-unix.sh --select 1 --yes
Replace 1 with the index shown by the list command.
Remove agents that are not healthy
Use this when cleanup is needed because an agent no longer connects, has certificate or trust problems, or is an old inactive install.
Windows:
.\cleanup-agent-windows.ps1 -RemoveNotConnecting -DryRun
.\cleanup-agent-windows.ps1 -RemoveBadCert -DryRun
.\cleanup-agent-windows.ps1 -RemoveUnknown -DryRun
.\cleanup-agent-windows.ps1 -RemoveInactive -DryRun
.\cleanup-agent-windows.ps1 -RemoveNotConnecting -RemoveBadCert -RemoveUnknown -RemoveInactive -ExcludeCurrent -Yes
Unix-like systems:
sudo sh cleanup-agent-unix.sh --remove-not-connecting --dry-run
sudo sh cleanup-agent-unix.sh --remove-bad-cert --dry-run
sudo sh cleanup-agent-unix.sh --remove-unknown --dry-run
sudo sh cleanup-agent-unix.sh --remove-inactive --dry-run
sudo sh cleanup-agent-unix.sh --remove-not-connecting --remove-bad-cert --remove-unknown --remove-inactive --exclude-current --yes
-ExcludeCurrent and --exclude-current tell the cleanup tool not to remove the agent that is currently running the cleanup request.
Remove all local TvRMM agents
Use this only when the endpoint should have no TvRMM agent afterward, such as before decommissioning, rebuilding, or handing the machine to another owner.
Windows:
.\cleanup-agent-windows.ps1 -All -DryRun
.\cleanup-agent-windows.ps1 -All -Yes
Unix-like systems:
sudo sh cleanup-agent-unix.sh --all --dry-run
sudo sh cleanup-agent-unix.sh --all --yes
Endpoint type notes
Windows
Use an elevated PowerShell session. If Windows still shows TvRMM in Programs and Features immediately after cleanup, refresh the view or reopen Settings.
macOS
Use the Unix cleanup script with sudo. The script handles TvRMM's local macOS service registration and related support files.
Linux and BSD
Use the Unix cleanup script with sudo or as root. This includes ordinary Linux servers and desktops, FreeBSD-based systems, and Linux distribution variants.
NAS, firewall, and homelab hosts
Use the Unix cleanup script from an administrative shell on the device. Run cleanup during a maintenance window if removing the agent could interrupt a remote management session. This includes Proxmox VE, Unraid, Synology DSM, TrueNAS SCALE, UniFi OS, pfSense, and OPNsense.
Virtual machines and containers
If a VM or container has its own TvRMM agent installed inside it, clean it up from inside that guest. If the portal row is inventory-only, there is no guest agent to remove.
After cleanup
- Run the list command again and confirm the removed agent no longer appears.
- If the endpoint should no longer be managed, remove or retire it in the production portal.
- If you are reinstalling, generate a fresh bootstrap command from the production portal.
- Wait for the first heartbeat and audit before running endpoint actions again.