Agent overview

Overview

The DeviceQuest host agent (devicequest-agent) is a single binary that runs as a service on Linux and Windows hosts. It inventories the host it runs on, runs scans on behalf of the control plane from inside your network, and sends the results to DeviceQuest through the agent gateway. The agent always opens the connection itself, outbound, so hosts behind NAT or a firewall need no inbound rule.

You enroll agents from Admin → Enroll Agent (the Host Agent Setup page) and manage enrolled agents from Admin → Host Agents. Both pages need the admin:manage permission.

Platforms

The Linux service needs systemd. The Windows service runs as LocalSystem and starts automatically with Windows.

How the agent connects

The agent connects to the agent gateway, a gRPC service in the DeviceQuest control plane.

1. You issue a one-time bootstrap credential on the Enroll Agent page. It is valid for 5 minutes to 24 hours (60 minutes by default).
2. The install command passes the credential to the agent. On its first start the agent enrolls with the gateway and receives its own agent identity and token.
3. The agent saves its enrollment in enrollment.json in its data directory and uses it from then on. The bootstrap credential is no longer needed.
4. The agent keeps one long-lived connection open for commands, sends a heartbeat every 30 seconds, and pushes scan results and telemetry over the same gateway.

The gateway is reached in one of two ways:

Deployment modes

The agent works with control planes running in hybrid or saas mode, the two modes that run the agent gateway. You pass the mode to the agent with -mode:

• The one-command install served by your control plane uses -mode saas and TLS.
• The install script shown on the Enroll Agent page uses -mode hybrid, or -mode saas when the control plane runs in SaaS mode. If your control plane reports another mode (for example onprem with the agent gateway switched on), the page still uses hybrid and explains why under Why not …?

What the agent collects

The agent runs a local inventory scan as soon as it starts and then every 24 hours (change this with -auto-local-scan). The results appear on the host’s asset in DeviceQuest, matched to an existing asset by its identifiers or created as a new one.

Linux

Windows

GPU telemetry

When GPU telemetry is switched on (-gpu-telemetry-interval, or Enable GPU telemetry in Remote SSH deploy), the agent reads every GPU on the host at the interval you set and reports, per GPU:

• vendor, model, UUID, PCI bus ID, architecture, compute capability or GFX target, and driver version;
• memory total and used, GPU and memory utilisation;
• power draw and power limit, temperature, SM and memory clocks, and fan speed.

The Linux service runs with the video and render groups, so it can read GPU devices without root. Hosts without a GPU, or without the vendor tool, simply report no GPU readings.

Agent health

Every heartbeat also reports the agent’s version, CPU and memory use, disk usage, and how many scans it has completed and failed. Admin → Host Agents shows the version and the time of the last heartbeat.

Offline buffer

If the agent cannot reach the gateway, it keeps scan observations in a local SQLite buffer, agent_buffer.db in its data directory, and sends them when the connection returns. The buffer holds up to 100,000 observations or 50 MB. When it is full, the oldest observations are dropped first.

Commands

Administrators send commands to an agent from Admin → Host Agents. Commands are queued and delivered over the agent’s open connection, or when an offline agent next checks in.

Each command moves through these statuses in the command history:

Agent statuses

Files on the host

The data directory holds the agent’s token. On Linux it belongs to the devicequest-agent user. On Windows only SYSTEM and the Administrators group can open it.

Related pages

• Install on Linux
• Install on Windows
• Remote SSH deploy
• CLI reference
• Updates, revoke and uninstall
• Administration → Enroll agent
• Administration → Host agents