Skip to main content

Get Started: Agent Uninstall Protection

Agent Uninstall Protection ensures continuous device management by preventing unauthorized removal of the JumpCloud agent on your devices. Protection applies automatically to devices that have the JumpCloud agent installed, and uninstall activity is logged in Directory Insights. By default, attempting to remove the JumpCloud agent via standard uninstallation methods requires a per-device maintenance token to proceed with uninstallation. You can exempt selected devices from protection using OS-specific Disable Agent Uninstall Protection policies, letting you update or uninstall the agent for maintenance and troubleshooting. Applying these policies removes the maintenance token requirement for uninstalls, and JumpCloud does not log uninstall events in Directory Insights for associated devices.

Prerequisites:

Considerations:

  • Protection is enabled by default for all devices with the JumpCloud agent installed, including Apple devices managed by a third-party MDM that still run the JumpCloud agent for user management or other features, unless disabled by a policy.
  • Maintenance token validation works on the device without network connectivity, similar to a TOTP code.
  • Uninstall events appear in Directory Insights for online devices that are protected. Devices without network connectivity queue events and send them after reconnecting.

Viewing Agent Uninstall Protection Settings​

  1. Log in to the JumpCloud Admin Portal.
Important

If your data is stored outside of the US, check which login URL you should be using depending on your region. If your organization uses LDAP, RADIUS, or requires firewall allow list configuration, the Fully Qualified Domain Names (FQDNs) will also be region specific. See JumpCloud Data Centers for the URLs, FQDNs, and IP addresses.

  1. Go to Device Management > Devices and click Settings.
  2. Under Agent Uninstall Protection, review default protection information and learn more about creating exemption policies.

Accessing Agent Uninstall Protection​

You can view a device's protection status and maintenance token directly from the Device details when you need to authorize an uninstall.

To access Agent Uninstall Protection from a device:

  1. From the JumpCloud Admin Portal, go to Device Management > Devices.
  2. Select the Devices tab, then select the desired device by clicking on the device row.
  3. In the Highlights tab under Agent Uninstall Protection, view the status:
    • On: The device is not exempted by policy and a per-device maintenance token has been generated.
    • Off: An exemption policy applies to the device for its operating system.
    • Failed: The device is not exempted by policy, but the maintenance token has not been generated.
  4. You can also view the maintenance token, the timestamp for when protection was last set, and the timestamp for when the token was last rotated.
note

Agent Uninstall Protection shows On even if Agent Status is Inactive. Use Agent Status to confirm agent presence.

tip

To view the protection status for all devices at once, add the Agent Uninstall Protection column to the Devices list. See Column Management to learn more.

Viewing the Maintenance Token​

Each protected device has a unique maintenance token. Authorized admins can view the token from the Device when they need to approve an uninstall.

To view the maintenance token:

  1. From the JumpCloud Admin Portal, go to Device Management > Devices.
  2. Select the Devices tab, then select the desired device by clicking on the device row.
  3. In the Highlights tab under Agent Uninstall Protection, click View Maintenance Token.

If protection is enabled (On) and you view the token but do not uninstall the agent, the token automatically rotates 60 minutes after you view it. Rotation generates a new token and pushes it to that device. There is no manual regenerate control. Token validation works whether the device is online or offline.

Disabling Agent Uninstall Protection Using Policies​

You can create separate Disable Agent Uninstall Protection policies for macOS, Windows, and Linux. The policy name is the same on each OS; choose the correct OS tab when you add the policy. Disabling Agent Uninstall Protection does the following:

  • Uninstall protection status turns Off.
  • Uninstalling the agent using standard methods doesn’t require the maintenance token.
  • JumpCloud does not log uninstall events in Directory Insights.

See the following articles to learn how to create exemption policies:

Authorizing a Local Uninstall​

Use these steps for a one-time authorized local uninstall when Agent Uninstall Protection Status is On.

When possible, delete an Active, System Reporting device from the Admin Portal or the JumpCloud API instead. Remote removal doesn't require the maintenance token. If you need to uninstall the agent without a token on a set of devices, assign a Disable Agent Uninstall Protection policy for that operating system instead. See Install or Uninstall the JumpCloud Agent for all uninstall methods.

To uninstall the agent with the maintenance token:

  1. View the maintenance token for the device.
  2. On the device, run the uninstall script included with the agent as an administrator:
Operating SystemCommand
macOSIn Terminal, run sudo /opt/jc/bin/removeAgent
WindowsIn an elevated PowerShell prompt, run & "C:\Program Files\JumpCloud\removeAgent.ps1"
LinuxIn a terminal, run sudo /opt/jc/bin/removeAgent
  1. Enter the maintenance token when prompted.
  2. After a successful local uninstall, delete the device from the Admin Portal if it remains.
note

Token validation works without network connectivity. After you view the token, it rotates 60 minutes later if protection remains enabled and the agent remains installed.

Monitoring Uninstall Activity​

Directory Insights logs failed uninstall attempts (uninstall_attempt_failed), successful uninstalls (uninstall_success), and audit events for exemption policy creation, deletion, and assignment changes. Every uninstall attempt is logged, identifying the specific device and the user.

Uninstall events do not appear when a device is exempted by a policy. For exempted devices, JumpCloud does not log uninstall events in Directory Insights; Directory Insights only records the audit events related to the exemption policy's creation, assignment, or removal.

You can use all event types introduced by Agent Uninstall Protection as triggers in event-based Workflows to create custom alerts, such as notifying your team when an uninstall attempt fails. See Get Started: Workflows and Create an Event Based Workflow to learn more.

Understanding the End User Experience​

When a user starts a command line or script based uninstallation workflow on a supported OS (Windows, macOS, and Linux), the JumpCloud agent prompts for the device’s maintenance token. A valid token must be entered to proceed with agent uninstall.

note

Windows allows programs to be uninstalled via Programs and Features, which is also protected by Agent Uninstall Protection.

  • A missing or incorrect token stops the uninstall.
  • A valid token allows the uninstall to continue.
  • Token validation works without a network connection.
  • JumpCloud records whether the attempt failed or succeeded.

When disabled via policy, the operating system’s standard uninstall experience remains unchanged.

Was this information helpful?