Skip to content
DeviceQuest DeviceQuest DeviceQuest Docs User Documentation

Documentation

Install the agent on Windows

Enroll a Windows host with the PowerShell install command and check that the DeviceQuestAgent service is running.

Overview

You install the agent on Windows from an elevated PowerShell, with a command you copy from Admin → Enroll Agent. The command downloads devicequest-agent.exe, checks its SHA-256, registers the DeviceQuestAgent Windows service and enrolls it with a one-time bootstrap credential. The service starts automatically with Windows.

Before you start

  • Windows 10, Windows 11 or Windows Server, x64.
  • A PowerShell session started with Run as administrator.
  • Outbound access from the host to your DeviceQuest URL on port 443 and to the agent gateway (your DeviceQuest host on 443 for a Kubernetes deployment, or the control plane on 50051 for a direct connection).
  • The admin:manage permission in DeviceQuest.

Get the install command

  1. Open Admin → Enroll Agent. Old links to the Windows agent page open the same page with Windows selected.
  2. Under Choose the target platform, select Windows. The Architecture is amd64.
  3. Under Issue a bootstrap credential, enter a Target name, for example the computer name, and set Credential lifetime (minutes) if needed.
  4. Click Issue one-time credential. Copy the credential if you want to keep it; it is shown only once.
  5. Under Run the install script, click Copy script.

The fields of each step are described in Install on Linux; they are the same for Windows.

Install with one command

When your deployment serves agent downloads, step 4 shows one PowerShell command:

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12; & ([scriptblock]::Create((Invoke-RestMethod -UseBasicParsing 'https://dq.example.com/api/v1/agent/install.ps1?token=<one-time-agent-credential>')))
  1. Open PowerShell with Run as administrator on the Windows host.
  2. Paste the command and press Enter.

The installer install.ps1:

  1. enables TLS 1.2 and checks that PowerShell runs as Administrator;
  2. creates C:\Program Files\DeviceQuest Agent;
  3. stops a running DeviceQuestAgent service and waits up to 30 seconds for it to stop;
  4. downloads devicequest-agent.exe, checks its SHA-256 against the value the server baked into the script, and stops if they differ;
  5. runs devicequest-agent.exe install -gateway <gateway> -mode saas -tls -enrollment-credential <credential>.

It ends with Installed. Service: DeviceQuestAgent.

devicequest-agent.exe install:

  1. removes an existing DeviceQuestAgent service, so running the command again is the way to repair or re-enroll an agent;
  2. creates the data directory C:\ProgramData\devicequest-agent and limits access to SYSTEM and the Administrators group, because it holds the agent’s token;
  3. removes an old enrollment.json when you pass a new credential;
  4. creates the service DeviceQuest Asset Management Agent (DeviceQuestAgent) with automatic start, running as LocalSystem;
  5. starts the service, which enrolls with the gateway.

Installer messages

MessageWhat to do
Run PowerShell as Administrator.Close PowerShell and start it again with Run as administrator.
This server has no Windows agent build.Ask your DeviceQuest operator to publish the windows-amd64 build.
The DeviceQuestAgent service did not stop within 30 seconds.Stop the service in Services, then run the command again.
Checksum mismatch (…), not installing.The download was altered or incomplete. Run the command again.
devicequest-agent install failed (…)Read the line printed above it, for example connect to service manager (run as Administrator).
service DeviceQuestAgent is still marked for deletion; close the Services console and retryClose the Services console and any other tool that holds the service open, then run the command again.
install command not found or expired; ask your admin for a new oneThe credential in the URL is unknown, revoked or expired. Issue a new one.

Install with the manual script

When your deployment does not serve the one-command install, step 4 shows a PowerShell script that downloads the agent from the Portal download URL and registers the service itself.

  1. PowerShell — Windows: the script language for Windows.
  2. Copy script: copies the script to the clipboard.
  3. The script, with your gateway, the download URL and the credential filled in.
  1. Click Copy script.
  2. Open PowerShell with Run as administrator on the host, paste the script and run it.

The script installs the agent to C:\ProgramData\DeviceQuest\Agent, which is also its data directory, creates and starts the DeviceQuestAgent service, and waits up to 60 seconds for enrollment.json to appear. After the agent enrolls, it removes the bootstrap credential from the saved service command and restarts the service. It prints DeviceQuest Agent enrolled. Bootstrap credential removed from the service command.

If enrollment takes longer, the script warns Enrollment state was not created within 60 seconds. Check gateway reachability and service logs before removing the credential. Check that the host can reach the gateway, then run the script again with a new credential.

GPU telemetry

To collect NVIDIA GPU telemetry with nvidia-smi, add -gpu-telemetry-interval <seconds> to the install command, for example:

& 'C:\Program Files\DeviceQuest Agent\devicequest-agent.exe' install -gateway dq.example.com:443 -mode saas -tls -gpu-telemetry-interval 60 -enrollment-credential '<one-time-agent-credential>'

Install paths

ItemOne-command installManual script
ProgramC:\Program Files\DeviceQuest Agent\devicequest-agent.exeC:\ProgramData\DeviceQuest\Agent\devicequest-agent.exe
Data directoryC:\ProgramData\devicequest-agentC:\ProgramData\DeviceQuest\Agent
Enrollment stateC:\ProgramData\devicequest-agent\enrollment.jsonC:\ProgramData\DeviceQuest\Agent\enrollment.json
Offline bufferC:\ProgramData\devicequest-agent\agent_buffer.dbC:\ProgramData\DeviceQuest\Agent\agent_buffer.db
Service nameDeviceQuestAgentDeviceQuestAgent
Display nameDeviceQuest Asset Management AgentDeviceQuest Agent

Verify the installation

  1. Check the service in PowerShell:

    Get-Service DeviceQuestAgent

    Expected: Status is Running.

  2. In DeviceQuest, open Admin → Host Agents. The agent appears under Enrolled agents as windows/amd64 with the status online.

  3. After the first local inventory scan, the host’s asset shows its installed software, hotfixes, services, users, open ports and disks.

A Windows agent can also act as a bridge agent for WMI scans of other Windows hosts. Choose it as the bridge agent when you create a scan schedule; see Scan schedules.