Skip to content
DeviceQuest DeviceQuest DeviceQuest Docs User Documentation

Documentation

Updates, revoke and uninstall

Update an agent to a new version, revoke an agent or a bootstrap credential, and remove the agent from a Linux or Windows host.

Overview

After an agent is enrolled, you manage its lifecycle from two admin pages and from the host itself:

  • Admin → Host Agents: update an agent and revoke it.
  • Admin → Enroll Agent: revoke bootstrap credentials you no longer need.
  • On the host: devicequest-agent uninstall removes the service.

Update an agent

Agent updates are signed. When you update an agent, it downloads the new build for its own operating system and architecture from the agent gateway, verifies the signature, installs the new binary and restarts its service. Linux and Windows agents update the same way, and the agent keeps its enrollment, data directory and settings.

  1. Open Admin → Host Agents.
  2. Under Enrolled agents, select the agent, for example linux/amd64.
  3. On the Manage tab, under Commands, type the target version in Version (optional), for example 1.4.0. Leave it empty to install the current release.
  4. Click Update agent. The button reads Queueing… while the command is queued, then a notice confirms Queued update for linux/amd64.
  5. Open the Command history tab and click Refresh history. The Update command moves to completed when the new version is installed.
  6. After the service restarts, the Version field of the agent shows the new version.

What the agent does on each platform:

PlatformSteps
LinuxDownloads the build, verifies its signature, replaces /usr/local/bin/devicequest-agent atomically and restarts the devicequest-agent systemd unit.
WindowsDownloads the build, verifies its signature, stops the DeviceQuestAgent service, replaces devicequest-agent.exe in the install folder and starts the service again.

A build whose signature does not verify is never installed; the command ends in error with the reason under Show details.

An offline agent receives the update when it next checks in. The Manage tab tells you when the agent last reported.

Publish an agent update

The gateway serves updates from the directory in the control-plane setting DEVICEQUEST_AGENT_UPDATE_ARTIFACT_DIR. Put one signed build per platform there, named:

PlatformFile name
Linux x86-64agent-<version>-linux-amd64
Linux ARM64agent-<version>-linux-arm64
Windows x64agent-<version>-windows-amd64.exe

For example, agent-1.4.0-linux-amd64. The version you type in Version (optional) must match <version> in the file name. If no build exists for the agent’s platform, the Update command ends in error with artifact for version "…" not found.

Update by re-installing

You can also update an agent by running the install command again with a new bootstrap credential. The install replaces the binary and service, then the agent enrolls again. See Install on Linux and Install on Windows.

Revoke an agent

Revoking an agent cuts it off from DeviceQuest. Use it when a host is retired, compromised, or re-imaged.

  1. Open Admin → Host Agents and select the agent.
  2. Click Revoke next to its status.
  3. Read the confirmation: Revoke linux/amd64? The agent is disconnected on its next check-in and can no longer send data or receive commands. To bring this host back, re-run the install command with a new install token.
  4. Click Revoke to confirm, or Cancel.

The notice Revoked linux/amd64. It is disconnected on its next check-in. appears, and the agent’s status changes to revoked. On the Manage tab, the command buttons are disabled and a note explains how to enroll the host again.

On the host, the agent logs gateway rejected this agent (revoked or token invalid); re-run the install command to re-enroll. The service stays installed but cannot connect. To bring the host back, issue a new bootstrap credential and run the install command again. To remove the agent completely, also uninstall it.

Revoke a bootstrap credential

A bootstrap credential is only needed until the agent enrolls: the first enrollment uses it up, and it leaves the list. Revoke credentials that were never used or that you issued by mistake, so nobody can enroll an agent with them.

  1. Active bootstrap credentials: every credential that has not been used or revoked yet, newest first, with the number of credentials.
  2. Prefix: the first characters of the credential, so you can match it to a command you copied. The full credential is never shown again.
  3. Expires: when the credential stops working for enrollment.
  4. Last used: when an agent last used it, or Never.
  5. Status: Active or Expired.
  6. Revoke: revokes the credential after you confirm.

  1. Open Admin → Enroll Agent and scroll to Active bootstrap credentials.

  2. Find the credential by Name and Prefix.

  3. Click Revoke.

    1. The name of the credential you are revoking.
    2. Revoke: revokes it. Cancel closes the dialog without changes.

  4. Click Revoke to confirm. The credential is removed from the list.

Revoking cannot be undone. An install command that contains a revoked credential stops working at once. Agents that already enrolled keep their own token, so revoking a credential does not disconnect them; to cut off an enrolled agent, revoke the agent.

Credential statuses

StatusMeaningNext possible status
ActiveThe credential can enroll one agent until it expires. Once an agent enrolls with it, it leaves the list.Expired, or removed when used or revoked
ExpiredThe lifetime you set has passed. It can no longer enroll an agent. Revoke it to remove it from the list.Removed when revoked

If the list cannot load, it shows Could not load bootstrap credentials with a Retry button. With no credentials, it shows No active bootstrap credentials.

Uninstall the agent

Uninstalling removes the service from the host. Revoke the agent in DeviceQuest as well, so its enrollment can no longer be used.

Linux

sudo /usr/local/bin/devicequest-agent uninstall

This:

  1. stops and disables the devicequest-agent service;
  2. removes /etc/systemd/system/devicequest-agent.service and /etc/devicequest-agent/agent.env;
  3. reloads systemd.

It prints devicequest-agent uninstalled (state in /var/lib/devicequest-agent preserved).

The data directory /var/lib/devicequest-agent and the devicequest-agent user stay on the host, so a later install keeps the enrollment. To remove everything:

sudo rm /usr/local/bin/devicequest-agent
sudo rm -rf /var/lib/devicequest-agent /etc/devicequest-agent
sudo userdel devicequest-agent

Windows

In an elevated PowerShell:

Stop-Service DeviceQuestAgent
& 'C:\Program Files\DeviceQuest Agent\devicequest-agent.exe' uninstall

This stops the DeviceQuestAgent service and deletes it. The data directory C:\ProgramData\devicequest-agent stays on the host. To remove everything:

Remove-Item -Recurse -Force 'C:\Program Files\DeviceQuest Agent'
Remove-Item -Recurse -Force 'C:\ProgramData\devicequest-agent'

For an agent installed with the manual script, the program and data are both in C:\ProgramData\DeviceQuest\Agent.