Skip to main content

Manage and Verify Agents

After you deploy, manage the fleet from Configure > Agents. A notice on the Home dashboard about agents that need attention or are offline opens this list with the matching filter, sub-organizations included.

When data is flowing, ask questions with AI or confirm a citation in Explore.

The Agents list​

Each row has one badge for its type (workstation, server, or an ingest key), its connectivity and its collection state.

Filter chips:

  • All
  • Needs attention (collection or health problems)
  • Offline (not checking in)
  • Inactive (silent for a long time)

Sort by health, name, or last check-in. Sub-organizations are included by default, so an MSP sees its clients' endpoints in one list.

Select a device to edit its description, or to delete or undelete it. Clone detection finds machines that share one credential, such as a cloned image that did not enroll again. See Agent identity and cloning.

Change Ownership moves a selected device to another organization (for most MSPs, a client):

  • It is the fix for an endpoint onboarded under the wrong organization, and for a device that changes hands.
  • The move holds while the endpoint keeps its local enrollment data. Also change the endpoint's deployment package to name the new organization. Otherwise a wipe or reimage enrolls the endpoint in the old organization as a new device.
  • Data collected before the move stays with the organization that owned the device at the time.

See Moving devices and organizations.

If a row says the agent is waiting for its data feed pack, classic Event Log collection has not started yet. That should clear quickly. If it lasts about an hour, see Troubleshooting.

Agent detail​

Select a row. The pane shows the same status pills as the list. When the agent needs attention it adds a line in plain words, including the stop reason when the Windows service stopped for a shutdown, an uninstall or an upgrade.

Expanders:

  • Properties: organization, description.
  • System Details: OS, device class (workstation vs server, domain-controller role when reported), agent version, data feed pack version, update status, when data last arrived and when the agent last checked in.
  • Data feeds: per-feed collection (quiet and caught up vs behind or stuck), missed-event notices on Event Log feeds, matched-file counts on file sources. What each state means: Collection health.

How automatic updates work​

The agent is cloud-managed. It checks the signed CDN for a newer build on your workspace's release ring, verifies signatures, and applies the update without a technician visit per endpoint.

How soon a published build is picked up depends on the ring: within a few hours on Early Access, and within about a day on Stable. The first check waits a while after startup, so a fleet that reboots together does not check all at once. Workspace policy can force or pause updates. The update line on the detail pane shows each agent's update state.

After an update, System Details shows the new agent version and data feed pack version at the agent's next check-in.

Confirm install on an endpoint​

The reliable presence check is the Windows service, not the MSI product code (the GUID changes across versions). The service name is SparkLogsAgent and its display name is "SparkLogs Agent":

Get-Service SparkLogsAgent

Use this same check in RMM and Intune detection rules. See RMM mass-deploy, NinjaOne, and Microsoft Intune.

Verify data is arriving​

Open Explore and confirm events from the endpoint are arriving in the expected organization.

If an agent does not appear or no data arrives, see Troubleshooting.

Delete and remote uninstall​

Deleting a device hides it from the fleet and stops it from sending data. The delete dialog also asks what should happen to the agent still on the endpoint:

  • After N days (60 by default): a grace period, so an accidental delete or a machine that comes back can be undeleted with nothing lost.
  • Immediately.
  • Never: leave the agent installed and idle.

An optional checkbox also removes local agent state on the endpoint at uninstall time (the same cleanup as PURGE_STATE=1 below). The dialog shows the computed uninstall date, and the deleted device's detail pane shows the same date.

To change the schedule later, select the deleted device and use Uninstall Schedule; the dialog opens on Keep the current schedule so reviewing it changes nothing. Undelete cancels any pending uninstall and the endpoint resumes on its own, typically within a few hours.

Remote uninstall needs agent 1.9.8 or newer on the endpoint, and the endpoint has to be powered on to receive it. Once a deleted device's agent has checked in and gone quiet, the detail pane shows Agent confirmed dormant with the date; a device that never shows it is powered off or running an older agent. When the scheduled date arrives, the agent uninstalls at its next check-in and finishes cleanup on the endpoint within a day.

Uninstall and reinstall​

Uninstalling the agent removes the Windows service and binaries.

  • By default, local enrollment data and agent state stay on the host, including captured log data not yet uploaded. A reinstall on the same machine continues the same enrollment: same device record, same organization, same workspace.
  • PURGE_STATE=1 on the uninstall command wipes that local state: local identity, all agent state on the endpoint, buffered log data not yet uploaded, agent logs, and crash dumps.
  • A purge leaves the agent's Windows Event Log message file and event source registration in place, so the agent's past events still render correctly in Event Viewer.
  • A purge does not delete the device record in SparkLogs. Reinstalling after a purge needs the registration token again.
  • After a purge, the endpoint enrolls into the organization its installer points at (the registration token's organization, or the client organization its RMM or PSA client ID matches). It returns to its device record when that organization holds it, and enrolls as a new device when the record belongs to another organization.
  • The same applies to a machine rebuilt from an image or reverted by a disk-restore tool; see Agent identity and cloning.
  • Reinstalling never moves a device record to another organization, and a registration token never takes over a device record that belongs to another client. Use Change Ownership; see Moving devices and organizations.

If there is no device record to return to, what happens depends on why:

  • You deleted the device on purpose: reinstalls into the same organization stay blocked until you undelete it on Configure > Agents. Installing with a different client's registration token or client ID enrolls the machine there as a new device.
  • The record was removed some other way (rare): the install succeeds and the device gets a new identity.

Silent uninstall with purge:

# Read MSI product code from registry
$productCode = (Get-ItemProperty -Path 'HKLM:\SOFTWARE\SparkLogs\Agent' -Name ProductCode -ErrorAction Stop).ProductCode
# Uninstall the agent with PURGE_STATE=1 to clear agent identity and state
$p = Start-Process msiexec -Wait -PassThru -ArgumentList '/x',$productCode,'/qn','PURGE_STATE=1','/l*v',"$env:TEMP\SparkLogsAgent-uninstall.log"
# Exit code 0 means success, or 3010 means a reboot is required before uninstall is complete (uncommon)
$p.ExitCode

Omit PURGE_STATE=1 or uninstall via any other method for the agent to keep its identity and state. NinjaOne's native Uninstall Program is a non-purge path; see NinjaOne.