Documentation

Agent CLI reference

Every devicequest-agent subcommand, flag and environment variable, plus the control-plane settings that agents depend on.

Overview

devicequest-agent (devicequest-agent.exe on Windows) has four subcommands. The service runs run; you use install, uninstall and version by hand. Flags use a single dash (-gateway); a double dash (--gateway) also works.

devicequest-agent [run] [flags]
devicequest-agent install [flags]
devicequest-agent uninstall
devicequest-agent version

Subcommands

Subcommand	What it does	Needs
`run`	Starts the agent in the foreground: connects to the gateway, enrolls on first start, then sends heartbeats, runs commands and scans. This is the default, so `devicequest-agent -gateway …` is the same as `devicequest-agent run -gateway …`. On Windows, when started by the service manager, it runs as the `DeviceQuestAgent` service.	`-mode hybrid` or `-mode saas`
`install`	Installs the agent as a service and starts it. Linux: systemd unit `devicequest-agent`, see Install on Linux. Windows: service `DeviceQuestAgent`, see Install on Windows. Running it again replaces the existing installation.	root (Linux) or Administrator (Windows); `-mode hybrid` or `-mode saas`
`uninstall`	Stops and removes the service. Keeps the data directory, so a later install can reuse the enrollment. See Updates, revoke and uninstall.	root (Linux) or Administrator (Windows)
`version`	Prints `devicequest-agent <version>` and exits.	—

Flags

run and install accept the same flags. install writes them into the service, so the service starts with the same settings.

Flag	Environment variable	Default	Description
`-gateway <host:port>`	—	`localhost:50051`	Agent gateway address. Use `<DeviceQuest host>:443` through a Kubernetes ingress, or `<control plane>:50051` for a direct connection.
`-mode <mode>`	`DEVICEQUEST_MODE`	(empty)	`hybrid` or `saas`. Required: with any other value the agent stops with `agent gateway not available in on-prem mode`.
`-enrollment-credential <credential>`	`DEVICEQUEST_AGENT_ENROLLMENT_CREDENTIAL`	(empty)	One-time bootstrap credential from Admin → Enroll Agent. Used for the first enrollment only. On Linux, `install` stores it in `/etc/devicequest-agent/agent.env`, not in the unit file.
`-data-dir <path>`	—	Linux `/var/lib/devicequest-agent`; Windows `%ProgramData%\devicequest-agent`	Directory for `enrollment.json` and the offline buffer `agent_buffer.db`. On Linux, `install` creates it and gives it to the `devicequest-agent` user.
`-tls`	`DEVICEQUEST_AGENT_TLS` (`1`, `true` or `yes`)	off	Connect to the gateway over TLS and check its certificate against the system trust store. Required through a Kubernetes ingress.
`-ca-file <path>`	`DEVICEQUEST_AGENT_CA_FILE`	(empty)	PEM CA bundle for a gateway with a private certificate. Turns on TLS.
`-heartbeat <duration>`	—	`30s`	Time between heartbeats, for example `30s` or `1m`.
`-auto-local-scan <duration>`	—	`24h`	Time between automatic local inventory scans. The first scan runs at start. `0` turns automatic scans off.
`-gpu-telemetry-interval <seconds>`	`DEVICEQUEST_AGENT_GPU_TELEMETRY_INTERVAL`	`0`	Seconds between GPU telemetry readings. `0` turns GPU telemetry off.
`-log-format <format>`	—	`text`	`text` or `json`. Installed services use `json`.
`-version`	—	—	Prints the version and exits.

A flag on the command line wins over its environment variable.

The agent writes its log to standard output. On Linux, read it with journalctl -u devicequest-agent.

Examples

Install on Linux through a Kubernetes ingress:

sudo DEVICEQUEST_AGENT_ENROLLMENT_CREDENTIAL='<one-time-agent-credential>' \
  ./devicequest-agent install -gateway dq.example.com:443 -mode saas -tls

Install on Linux with a direct gateway connection and GPU telemetry every minute:

sudo ./devicequest-agent install \
  -gateway 10.0.0.5:50051 \
  -mode hybrid \
  -enrollment-credential '<one-time-agent-credential>' \
  -gpu-telemetry-interval 60

Install on Windows, in an elevated PowerShell:

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

Run in the foreground for troubleshooting, with the existing enrollment and a 5-minute inventory interval:

sudo -u devicequest-agent /usr/local/bin/devicequest-agent run \
  -gateway dq.example.com:443 -mode saas -tls \
  -data-dir /var/lib/devicequest-agent -auto-local-scan 5m

Stop the service first (sudo systemctl stop devicequest-agent) so only one copy runs. Use the same -gateway, -tls or -ca-file as the ExecStart line in /etc/systemd/system/devicequest-agent.service.

Print the version:

devicequest-agent version

Messages

Message	Meaning
`agent gateway not available in on-prem mode`	`-mode` is not `hybrid` or `saas`.
`install failed: -mode must be "hybrid" or "saas" (got "…")`	`install` was run without a valid `-mode`.
`install requires root; re-run with sudo`	Run `install` with `sudo` on Linux.
`uninstall requires root; re-run with sudo`	Run `uninstall` with `sudo` on Linux.
`connect to service manager (run as Administrator)`	Run PowerShell as Administrator on Windows.
`removed previous enrollment state; the agent will enroll with the new credential`	`install` received a new credential and cleared the old enrollment.
`devicequest-agent installed and started (systemctl status devicequest-agent)`	Linux install finished.
`devicequest-agent uninstalled (state in /var/lib/devicequest-agent preserved)`	Linux uninstall finished.
`gateway rejected this agent (revoked or token invalid); re-run the install command to re-enroll`	The agent was revoked. Re-enroll with a new credential.

Control-plane settings

These environment variables on the DeviceQuest control plane decide how agents connect, install and update. The Helm chart sets most of them for you; see Kubernetes agent gateway.

Variable	Default	Description
`DEVICEQUEST_MODE`	`onprem`	`hybrid` and `saas` run the agent gateway.
`DEVICEQUEST_AGENT_GATEWAY_PORT`	`50051`	gRPC port of the agent gateway.
`DEVICEQUEST_AGENT_GATEWAY_TLS_ENABLED`	`true` in hybrid and SaaS	Serve the gateway over TLS.
`DEVICEQUEST_AGENT_GATEWAY_TLS_CA_CERT`	—	CA certificate for the gateway.
`DEVICEQUEST_AGENT_GATEWAY_TLS_SERVER_CERT`	—	Gateway server certificate.
`DEVICEQUEST_AGENT_GATEWAY_TLS_SERVER_KEY`	—	Gateway server key.
`DEVICEQUEST_AGENT_GATEWAY_AUTH`	`mtls`	How agents authenticate: `mtls` (client certificates) or `token` (a per-agent token, for gateways behind an ingress).
`DEVICEQUEST_AGENT_GATEWAY_ADVERTISE_ADDR`	—	Gateway address that install commands and remote deploy give to agents, for example `dq.example.com:443`.
`DEVICEQUEST_PUBLIC_URL`	—	Public `https://` URL of DeviceQuest. Needed for the one-command install.
`DEVICEQUEST_PORTAL_URL`	—	URL that assets download the agent from during remote SSH deploy.
`DEVICEQUEST_AGENT_ARTIFACT_DIR`	`/agent-artifacts` in the control-plane image	Directory with the agent builds and `manifest.json` served by the one-command install.
`DEVICEQUEST_AGENT_UPDATE_ARTIFACT_DIR`	—	Directory with agent update builds, named `agent-<version>-<os>-<arch>` (`.exe` for Windows). See Updates, revoke and uninstall.