Skip to main content

Installing Host Agents

Create an enrollment profile from Agents → Install Agent. Lumetry shows the enrollment token once and renders both Linux and Windows commands with the current Lumetry endpoint. Each platform first downloads a secrets-free bootstrap, then runs it separately with elevated rights and the copy-once token. Installer locations are deployment-owned; copy the displayed commands rather than substituting a package URL from another environment.

Windows Server​

The Windows package supports 64-bit Windows Server 2019 and newer. First download the bootstrap from a regular PowerShell session:

$installer = Join-Path $env:TEMP "install-lumetry-agent.ps1"
Invoke-WebRequest -UseBasicParsing `
  "https://downloads.getlumetry.com/agents/latest/install.ps1" `
  -OutFile $installer

Then open an elevated PowerShell session and run the local bootstrap. The run command recomputes the deterministic temporary path, so it does not depend on a variable from the download session:

$installer = Join-Path $env:TEMP "install-lumetry-agent.ps1"
powershell.exe -ExecutionPolicy Bypass -File $installer `
  -ArtifactBaseUrl "https://downloads.getlumetry.com/agents/latest" `
  -BackendUrl "https://api.getlumetry.com" `
  -EnrollmentToken "lmtae_..."

For collector-first routing, add:

-CollectorUrl "http://collector.internal:4319"

To request placement in a topology Cluster during enrollment, add either -Cluster "ANVMBWEBWX" for a case-insensitive display-name match or -ClusterId "cls.anvmbwebwx" for an exact external-ID match. Do not supply both. If no Cluster has the supplied display name, Lumetry creates one and places the agent under it. Enrollment still succeeds without a group when the value is missing, is not a Cluster, or is ambiguous.

The bootstrap verifies the package checksum. The package installer also verifies Authenticode signatures before it creates the service.

The installed service:

  • is named LumetryAgent;
  • starts automatically after boot and has restart recovery configured;
  • runs under the dedicated Windows virtual account NT SERVICE\LumetryAgent;
  • stores identity, the offline queue, configuration, and local status under %ProgramData%\Lumetry\Agent;
  • writes operational messages to the Windows Application event log.

When IIS is installed, setup ensures the IIS Management Scripts and Tools role service is present and grants the dedicated service identity local read/method access to the IIS WMI namespace. The agent does not run as LocalSystem or as a local administrator.

The installer removes the enrollment token from the service environment after the host enrolls successfully.

Uninstall from an elevated PowerShell session:

& "$env:ProgramFiles\Lumetry\Agent\uninstall.ps1"

Uninstall removes the service, program files, and agent state. Use -KeepState only when intentionally preserving identity and buffered data for troubleshooting.

Linux​

First download the secrets-free Linux bootstrap shown by Lumetry:

wget -O lumetry-agent-install.sh \
  "https://downloads.getlumetry.com/agents/latest/install.sh"

Then enter a root shell with the privilege-elevation method approved for the target host, such as sudo, dzdo, or doas, and run the local bootstrap with the copy-once token. Lumetry does not assume which elevation tool is installed. The bootstrap selects x64 or arm64, downloads through curl or wget, verifies the package checksum, and installs the systemd service:

/bin/bash ./lumetry-agent-install.sh \
  --artifact-base https://downloads.getlumetry.com/agents/latest \
  --backend https://api.getlumetry.com \
  --enroll-token lmtae_...

Add --collector http://collector.internal:4319 for collector-first routing.

To request placement in a topology Cluster, add either --cluster=ANVMBWEBWX or --cluster_id=cls.anvmbwebwx. The external-ID form is the recommended automation key for existing CMDB-managed Clusters. Do not supply both. A new display name creates a Cluster; an ambiguous or invalid hint leaves the host unassigned without blocking enrollment.

Network behavior​

Agents make outbound connections only. With a collector configured, the agent tries the collector first and falls back to Lumetry directly when network policy allows. When neither complete path is available, metrics remain in the bounded local queue and upload after connectivity recovers.

Production deployments should use TLS for Lumetry and for collector connections that cross an untrusted network.