Windows - Maintenance Tasks - Cleanup Disconnected Automox Devices

What the disconnected endpoint cleanup Worklet does

This Automox Worklet™ identifies endpoints that have been disconnected from your Automox organization beyond a configurable age threshold and removes them through the Automox API. The Worklet calls the /api/servers endpoint to enumerate every endpoint in the target zone, calculates the elapsed time since each endpoint's last_disconnect_time, and compares that value against the ageLimit parameter (default 120 days). Endpoints with a null last_disconnect_time are skipped because they are still checking in.

The script reads five inputs: the apiKey Shared Secret, the orgID for the Automox zone you want to clean, an optional excludedDevices array of hostnames to protect, the ageLimit day count, and a dryRun flag that defaults to $true. When dryRun is enabled, the Worklet writes a DRY RUN line for each candidate to the Activity Log without calling the delete API. When dryRun is set to $false, the Worklet issues an HTTP DELETE against /api/servers/{deviceId}?o=$orgID for each qualifying endpoint and tallies successes and failures in separate ArrayLists.

The deletion is permanent. Re-onboarding a removed endpoint requires reinstalling the amagent on that machine, so the dry-run default exists to give you a review window before any destructive call goes out.

Why automate stale endpoint cleanup

Disconnected endpoint records accumulate quietly. Retired laptops, decommissioned servers, reimaged workstations, contractor machines, and short-lived build hosts all leave behind console entries that keep consuming a license seat and skewing the compliance percentage you report to leadership. Six months of unattended drift can leave hundreds of phantom endpoints inflating dashboards, hiding the active fleet's true patch posture, and pushing your seat count past the next billing tier.

Run this Worklet on a scheduled cadence so license renewal forecasts, compliance dashboards, and onboarding lifecycle policies use the actual endpoint population. The same API call a console operator would make by hand runs here on a schedule, with the dryRun guardrail and a full audit trail written to the Activity Log.

How disconnected endpoint cleanup works

1. Evaluation phase: The Worklet calls Invoke-RestMethod against https://console.automox.com/api/servers?o=$orgID&page=$page&limit=500 with a Bearer token built from the apiKey Shared Secret, then walks the paginated result set. For each endpoint, it skips hostnames present in the excludedDevices array, skips records with a null last_disconnect_time, casts the timestamp to [System.DateTime], and computes the day delta against [System.DateTime]::Now. If any endpoint's delta meets or exceeds ageLimit, evaluation exits 1 and flags the policy for remediation; otherwise it exits 0.

2. Remediation phase: Remediation re-walks the same paginated /api/servers list. For every endpoint past the age threshold, it projects a Select-Object report object (Device Name, Device ID, Last Disconnected Time, Days Disconnected) and constructs the delete URI https://console.automox.com/api/servers/{deviceId}?o=$orgID. When dryRun is $false, it issues Invoke-WebRequest -UseBasicParsing -Method Delete against that URI and appends the result to either the $successDelete or $failDelete ArrayList. When dryRun is $true, it writes a DRY RUN line per qualifying endpoint and makes no API call. After the loop, the Worklet renders both ArrayLists with Format-Table for audit evidence.

Disconnected endpoint cleanup requirements

• A single Windows endpoint scoped through Device Targeting to run this policy; the Worklet must not be broadcast across the fleet, because every targeted endpoint would independently delete every stale record.

• Automox Platform API key stored as a Shared Secret named apiKey with permission to list and delete endpoints in the target zone.

• Automox orgID set inline in the script for the zone you want to clean, matching the o= query parameter the script appends to every API call.

• ageLimit value in days that defines the disconnection window before deletion; the default is 120.

• Optional excludedDevices array of hostnames that must match the Automox console name exactly; common protections include build agents, jump hosts, and lab endpoints that legitimately stay offline for long periods.

• dryRun left at $true for the first run so you can review the candidate list in the Activity Log, then flipped to $false for the destructive run.

• Outbound HTTPS reachability to console.automox.com from the targeted endpoint.

Expected console inventory state after cleanup

After a live run with dryRun set to $false, every endpoint whose last_disconnect_time exceeded ageLimit is removed from the target Automox zone. The Activity Log shows up to two tables: a Successful Deletions table listing Device Name, Device ID, Last Disconnected Time, and Days Disconnected for each deleted endpoint, and a Failed Deletions table recording any DELETE call that raised an exception in the Try/Catch block. A subsequent evaluation finds no endpoints past the threshold and exits 0, so the policy reports compliant until new endpoints age into the window.

Validate the result in the Automox console Devices view by filtering on disconnected status; the count should drop by the number reported in the success table. Confirm license utilization on the Automox subscription page to verify the seats freed by deletion now read as available. For dry-run validation, scrub the Activity Log output for the DRY RUN lines and cross-check a sample of hostnames against your inventory of retired hardware before scheduling the live run. The Worklet does not touch any endpoint that is still checking in; if a removed endpoint later reconnects through a reinstalled amagent, it returns as a new console record with a fresh device ID.