Skip to content
DeviceQuest DeviceQuest DeviceQuest Docs User Documentation

Documentation

Remote SSH deploy

Push the agent to a Linux asset from its asset page over SSH, with optional GPU telemetry, and follow each step until it enrolls.

Overview

Remote deploy installs the agent on a Linux asset without you logging in to it. From the asset page, you pick an SSH credential; DeviceQuest issues a short-lived bootstrap credential, connects to the asset over SSH, runs the install, and waits until the new agent enrolls and sends its first heartbeat. Use it to add agents to hosts you already scan over SSH.

The Deploy agent button appears on the asset page for administrators. Starting a deployment also needs the scans:write permission.

Before you start

  • The asset has an IP address or a host name. DeviceQuest connects to the IP address first, then the host name.
  • An SSH scan credential that can log in to the asset. See Scan credentials.
  • The SSH user can run sudo:
    • with a password credential, DeviceQuest passes the same password to sudo, so no extra sudo setup is needed;
    • with a private key credential, the user needs passwordless sudo (NOPASSWD).
  • The asset can reach your DeviceQuest URL, to download the agent, and the agent gateway.
  • Your control plane has DEVICEQUEST_PORTAL_URL (the URL assets download the agent from) and DEVICEQUEST_AGENT_GATEWAY_ADVERTISE_ADDR (the gateway address agents dial) set. See CLI reference.

Screen tour

  1. Operating system: Linux or Windows. The dialog picks the asset’s operating system for you. For a Windows asset, it points you to Admin → Enroll Agent (Windows), where you copy the PowerShell install command.
  2. SSH credential: the SSH scan credential used to log in to the asset. The list shows only SSH credentials. If you have none, it reads No SSH credentials — add one under Scanning.
  3. Enable GPU telemetry: makes the new agent report GPU telemetry. On by default.
  4. Telemetry interval (seconds): how often the agent reads its GPUs. Minimum 5, default 15. Shown only when GPU telemetry is on.
  5. Deploy: starts the deployment. It is disabled until you choose an SSH credential.

Deploy the agent

  1. Open the asset in Asset Inventory.
  2. Click Deploy agent in the asset header.
  3. Check that Operating system is Linux.
  4. Choose the SSH credential.
  5. Leave Enable GPU telemetry on and set the Telemetry interval (seconds), or clear the box.
  6. Click Deploy.

The dialog switches to a progress list and checks the deployment every 3 seconds. Working… this can take up to ~90s. The steps are:

StepWhat happens
Issue credentialDeviceQuest issues a bootstrap credential named deploy-<asset ID>, valid for 30 minutes.
Connect (SSH)DeviceQuest loads the SSH credential from the vault.
Install agentDeviceQuest connects to the asset over SSH, downloads the agent from <portal URL>/downloads/agent-linux-amd64, stops any running agent, and runs devicequest-agent install with the gateway, -mode hybrid, the bootstrap credential and, when on, -gpu-telemetry-interval.
Enroll + heartbeatDeviceQuest waits up to 90 seconds for the new agent to enroll and send a heartbeat.

Each step shows ○ (waiting), … (running), ✓ (done) or ✗ (failed), with a detail line when there is one.

When all steps succeed, the dialog shows Agent deployed and enrolled. Click Done. The asset page reloads, and the agent appears in Admin → Host Agents.

The agent installed this way is the same as one installed by hand: the devicequest-agent systemd service described in Install on Linux.

Deployment statuses

StatusMeaningNext possible status
pendingThe deployment is recorded and about to start.running
runningA step is in progress.succeeded, failed
succeededThe agent enrolled and sent a heartbeat.—
failedA step failed. The dialog shows the reason.—

If a deployment fails

The failed step is marked ✗ and the dialog shows the error. Click Cancel to close it, fix the cause, and deploy again.

ErrorCause and fix
credential_id requiredChoose an SSH credential.
asset not found or has no hostThe asset has no IP address or host name. Add one, or scan the asset first.
remote deploy not configured: set DEVICEQUEST_PORTAL_URL and DEVICEQUEST_AGENT_GATEWAY_ADVERTISE_ADDRAsk your DeviceQuest operator to set both control-plane settings.
resolve credential: …The SSH credential could not be read. Check it under Scan Credentials.
ssh install: …SSH login failed or the connection dropped. Check the credential, the port and that the asset accepts SSH from the control plane.
install exited <code>: …The install script failed on the asset, for example because sudo needs a password for a key-based login, or the asset cannot download the agent.
agent did not enroll/heartbeat within timeoutThe agent was installed but did not reach the gateway in 90 seconds. Check that the asset can reach the gateway address, then look at journalctl -u devicequest-agent on the asset.