Install the agent on Linux

Overview

You install the agent on a Linux host with a command you copy from Admin → Enroll Agent. The command downloads the agent for the host’s architecture, installs it as the hardened systemd service devicequest-agent, and enrolls it with a one-time bootstrap credential. Use the one-command install when your deployment serves it, and the manual install script otherwise.

Before you start

• A Linux host with systemd, on x86-64 (amd64) or ARM64 (arm64).
• Root access on the host (sudo).
• Outbound access from the host to:
  • your DeviceQuest URL on port 443, to download the agent;
  • the agent gateway: your DeviceQuest host on port 443 for a Kubernetes deployment, or the control plane on port 50051 for a direct connection.
• The admin:manage permission in DeviceQuest, to open the Enroll Agent page.

Screen tour

The Enroll Agent page (titled Host Agent Setup) walks you through four steps. The header shows whether the Agent gateway is Enabled and the Control-plane mode.

Click to enlarge

Click to enlarge

Click to enlarge

After you click Issue one-time credential, the Credential issued box shows the credential. Copy this value now — it is shown only once and cannot be retrieved later. Click Copy credential to copy it, then I’ve saved it to close the box. The install command in step 4 already contains it.

Click to enlarge

Below the steps, Active bootstrap credentials lists every credential you have issued. See Updates, revoke and uninstall.

Install with one command

When your deployment serves agent downloads (on Kubernetes, with agentGateway.external.enabled=true), step 4 shows a single command:

curl -fsSL 'https://dq.example.com/api/v1/agent/install.sh?token=<one-time-agent-credential>' | sudo bash

1. Open Admin → Enroll Agent.
2. Under Choose the target platform, select Linux.
3. Enter a Target name and, if needed, change Credential lifetime (minutes).
4. Click Issue one-time credential.
5. Under Run the install script, click Copy script.
6. On the Linux host, paste and run the command.

The installer:

1. checks that it runs as root;
2. picks the build for the host’s architecture (x86_64 or aarch64);
3. downloads the agent from your DeviceQuest URL and checks its SHA-256 against the value the server baked into the script, and stops if they differ;
4. stops a running agent, if there is one;
5. runs devicequest-agent install with your gateway, -mode saas and TLS, which installs and starts the service and enrolls the agent.

It ends with Installed. Follow the agent log with: sudo journalctl -u devicequest-agent -f.

Private certificate authority

If your DeviceQuest certificate is issued by a private CA, copy the CA certificate to the host as ca.pem, and tick The server certificate is from a private CA (I have its ca.pem on the host) before you copy the command. The command becomes:

curl -fsSL --cacert ca.pem 'https://dq.example.com/api/v1/agent/install.sh?token=<one-time-agent-credential>' | sudo DEVICEQUEST_AGENT_CA_FILE="$PWD/ca.pem" bash

Run it from the directory that holds ca.pem. The installer copies the CA to /etc/devicequest-agent/ca.pem and starts the agent with -ca-file /etc/devicequest-agent/ca.pem.

Installer messages

Install with the manual script

When your deployment does not serve the one-command install, step 4 shows a script that downloads the agent from the Portal download URL and installs it:

#!/usr/bin/env bash
set -euo pipefail

# 1. Download the DeviceQuest agent
curl -fsSL -o devicequest-agent 'https://dq.example.com/downloads/agent-linux-amd64'
chmod +x devicequest-agent

# 2. Install as a systemd service. This creates the devicequest-agent system user,
#    writes the hardened unit, enrolls with the one-time credential, then starts it.
sudo ./devicequest-agent install \
  -gateway 'dq.example.com:50051' \
  -mode 'hybrid' \
  -enrollment-credential '<one-time-agent-credential>'

# 3. Verify
systemctl status devicequest-agent --no-pager

1. On the Enroll Agent page, select Linux and the host’s Architecture.
2. Check Gateway and Portal download URL. Both must be reachable from the host.
3. Enter a Target name and click Issue one-time credential.
4. Click Copy script and run the script on the host.

To check the binary yourself, click Verification checksum in step 2 and compare it with sha256sum devicequest-agent.

You can also run install directly with a binary you copied to the host. Add -tls when the gateway uses TLS with a publicly trusted certificate, or -ca-file <path> for a private CA:

sudo ./devicequest-agent install \
  -gateway dq.example.com:50051 \
  -mode hybrid \
  -enrollment-credential '<one-time-agent-credential>'

To turn on GPU telemetry at install time, add -gpu-telemetry-interval <seconds>, for example -gpu-telemetry-interval 60. See CLI reference for every flag.

What the install does

devicequest-agent install must run as root. It:

1. stops a running devicequest-agent service, if any;
2. copies itself to /usr/local/bin/devicequest-agent;
3. creates the system user devicequest-agent with no home directory and no login shell, if it does not exist;
4. creates the data directory (/var/lib/devicequest-agent by default) owned by that user;
5. when you pass a credential, writes it, and the GPU telemetry interval when set, to /etc/devicequest-agent/agent.env with mode 0600;
6. removes an old enrollment.json when you pass a new credential, so the agent enrolls again with it;
7. writes the unit /etc/systemd/system/devicequest-agent.service;
8. runs systemctl daemon-reload, then enables and restarts the service.

It prints devicequest-agent installed and started (systemctl status devicequest-agent).

The systemd unit

[Unit]
Description=DeviceQuest Asset Management Agent
Documentation=https://github.com/devicequest/platform
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=devicequest-agent
Group=devicequest-agent
SupplementaryGroups=video render
EnvironmentFile=-/etc/devicequest-agent/agent.env
ExecStart=/usr/local/bin/devicequest-agent run -gateway dq.example.com:50051 -mode hybrid -data-dir /var/lib/devicequest-agent -log-format json
Restart=always
RestartSec=5
StateDirectory=devicequest-agent
ReadWritePaths=/var/lib/devicequest-agent
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

• The service runs as the unprivileged devicequest-agent user and restarts 5 seconds after any exit.
• The credential is read from agent.env, so it never appears in the world-readable unit file.
• ExecStart adds -tls or -ca-file … when you installed with them.
• SupplementaryGroups=video render lets the agent read GPU devices for GPU telemetry.

agent.env

DEVICEQUEST_AGENT_ENROLLMENT_CREDENTIAL=<one-time-agent-credential>
DEVICEQUEST_AGENT_GPU_TELEMETRY_INTERVAL=60

The second line is present only when GPU telemetry is on. The directory /etc/devicequest-agent belongs to root; systemd reads the file before it starts the service as devicequest-agent.

Verify the installation

1. Check the service:

   systemctl status devicequest-agent
   

   Expected: active (running).

2. Follow the log:

   sudo journalctl -u devicequest-agent -f
   

   Expected, in JSON: enrollment successful with the agent_id, then agent started successfully.

3. In DeviceQuest, open Admin → Host Agents. The new agent appears under Enrolled agents as linux/amd64 (or linux/arm64) with the status online.

4. After the first local inventory scan, the host’s asset shows its packages, services, users, open ports and disks.

If the agent does not enroll

Re-install or re-enroll

Run the install command again with a new credential. install stops the running service, replaces the binary, removes the previous enrollment, and starts the service, which enrolls with the new credential. Your data directory and service user stay in place.

Related pages

• Agent overview
• Kubernetes agent gateway
• CLI reference
• Updates, revoke and uninstall
• Administration → Enroll agent
• Administration → Host agents