VDI and ephemeral agent lifecycle

A fleet can replace hundreds of machines while keeping roughly the same reporting capacity. Manage three separate concepts: the VM instance, its grouping, and its reporting time.

Prepare an image before enrollment

Open Agents → Add & deploy → Golden image / VDI. Choose the platform, name the desktop pool, and set the enrollment window and device limit. The package is reusable; new clones must enroll before the token expires or its device limit is reached.

1. Extract the ZIP on a clean source image.
2. Run "Install Service.cmd" /quiet as administrator on Windows, or sudo sh ./install-service on Linux or macOS.
3. Leave the service stopped, generalize the OS, and capture the image.
4. Boot a customized clone. It enrolls automatically with a fresh installation fingerprint and its own credentials.

Preparation refuses existing enrollment state, queued measurements, or a running agent service. It never clears them. Do not use Start Agent.cmd or start-agent on the source. The preparation marker prevents enrollment while the source machine identity is unchanged. A deployed clone binds that marker to its machine identity, so copying its enrolled state to a different machine fails closed.

Windows customization must change MachineGuid, normally through Sysprep. Linux clones must receive a unique /etc/machine-id; macOS VMs need distinct platform UUIDs. This requires a clean generalized image and a correctly configured clone workflow. The identity checks are protection against accidental copies, not hardware attestation. Keep enrollment state on instance-local storage, outside roaming profiles. A normal restart preserves identity; a fresh replacement clone receives a new one even when its hostname is reused.

For ongoing image provisioning, paste a tenant token into Install in seconds, select Prepare a golden image, and copy the command. The universal PowerShell installer accepts -PrepareImage; the curl installer accepts --prepare-image. These switches download an image-aware package and leave its boot service stopped. Image packages contain an enrollment credential; distribute the image only through your authorized deployment workflow. Revoking the token stops fresh enrollments without disconnecting already enrolled clones.

Golden-image and desktop-session features require a newly published agent build that advertises those capabilities, plus the updated server. Older builds remain available for ordinary installation; the server refuses to package unsupported flags.

Group coverage without merging identities

Set the pool agent label, for example Finance desktops. The image wizard assigns it to every new clone. Agents → Pools shows enrolled totals and enabled instances seen in the last five minutes. Open Manage instances for individual device configuration and status, or View sessions for users in that pool. Historical instances remain available; totals are not a count of simultaneously running desktops.

For commands using an existing token, pool membership comes from that token’s default agent tags. Install-token creation includes a default desktop-pool field. Existing agents can also be assigned the pool label in their configuration. A label groups hosts; it never becomes an enrollment identity.

Target a VDI pool with checks

A desktop pool is an agent label, not a network scope. Naming a pool does not create a network scope or a separate pool selector. For example, a pool named Finance desktops adds the label pool with the value Finance desktops to each clone enrolled from that image package.

1. In the test or check’s agent selection, choose the dynamic label selector instead of individual agent names.
2. Enter label key pool and label value Finance desktops, replacing the example with your exact pool name. Keep spelling, capitalization and spaces consistent.
3. Leave network scope unset to select that pool across networks, or add a network scope to restrict coverage. When both are supplied, agents must match both.
4. Save the check and verify its assignment and first result on a reporting clone. New matching clones become eligible as they enroll and report the required capabilities. Existing enrollment and check-placement limits still apply.

Configure the selector against the clones, not a running golden-image agent. The prepared source stays stopped and unenrolled. Use a desktop-pool label for host membership; do not rename every clone to the pool name or share credentials. An existing agent can join the pool by receiving the same pool label in its configuration.

For a Desktop Sessions check, select the platform to inspect, optionally set an exact user or client name, and choose the minimum connected-session count. Enable Collect Windows desktop sessions on the clones separately if you also want session history and the related host/endpoint test charts. The check does not enable that reporter automatically. This workflow requires the updated server and agent; release and live VDI validation are still pending.

Match a user’s endpoint to a desktop session

Install a separate private agent on the user’s physical computer or supported thin client in the same tenant. Its inventory name is the device name shown in Agents → Devices, normally its hostname. It is not the pool label, a network scope, or a special pairing tag.

For example, a session reporting client name LAPTOP-123 can match an endpoint agent named LAPTOP-123. The match ignores capitalization, but it does not expand a short hostname into a fully qualified name or translate a friendly display name. Renaming that agent to Sarah's laptop prevents this match unless the session reports that exact name too.

Matching runs automatically when exactly one other private, active agent in the same tenant has that name and has reported within 90 seconds of the observation. No manual pairing is required. Missing names or agents remain unidentified; duplicate recent names remain ambiguous. Enable the endpoint’s desired checks to have measurements available for the connection interval.

The matcher currently uses the history reporter’s Windows client name. Selecting Citrix or Horizon in a Desktop Sessions check does not feed that check’s platform metadata into the matcher. A check can find a session while its endpoint remains unidentified. Matching is inferred from reported names and never proves which endpoint opened the connection. See the connection evidence details.

Follow Windows users across hosts

Enable Collect Windows desktop sessions in the package wizard or universal installer (-DesktopSessions in PowerShell). The agent runs as LocalSystem and observes interactive Windows logons through WTS every 30 seconds. This collects account name, user SID, session identity, logon time and connection state. It does not collect passwords, screen contents or keystrokes.

Agents → Desktop sessions follows directory users by SID across hosts. Local accounts remain separate when their machine SIDs differ. A shared multi-session host keeps one device identity and reports multiple logon sessions. Host CPU, memory and network measurements are stored once, independent of how many users are signed in.

• Connected: the last observation reported a connected desktop.
• Disconnected: the logon exists but the desktop is disconnected.
• Ended: a complete observation confirmed that logon no longer exists. This is an observation time, not an exact Windows sign-out event timestamp.
• Unknown: no observation has arrived for 90 seconds. A destroyed or unreachable VM is not assumed to have cleanly signed out.

Partial observations do not end missing sessions. Missed activity during an agent outage or between polls cannot be reconstructed. Timelines retain observed transitions; opening a timeline shows the latest 200. Select a user to see their history across hosts. Host measurements for this session opens the observed interval, up to 30 days, with whole-host metrics when collection was enabled. It does not attribute all host CPU or traffic to that user.

Desktop session collection currently supports Windows. Linux and macOS support image preparation and distinct host identities, but do not report desktop logon sessions.

Review activity before retiring machines

Last-seen time shows recent reporting. Active status controls enrollment admission and does not prove the instance is online. Filter suspended and retired entries when reviewing history; do not confuse record count with simultaneous capacity.

For durable machines, reconfigure the existing agent instead of creating a replacement identity unnecessarily. Review the managing guide before bulk actions.

Budget ingestion across your fleet

Pricing follows accepted data, with no agent-hour charges. One or 100 private desktops ingesting the same GB have the same usage cost. Fleet schedules in the budget planner only estimate generated data; connection capacity limits still apply.

Reporting leases and replacement admission

Upgraded agents send a random process-local reporting session on configuration and ingestion requests. The server grants short reporting leases using its own database clock. A second session using an identity with an unexpired lease is refused and recorded as an identity conflict. An ordinary process restart may wait up to two minutes for its previous lease to expire.

This detects normal accidental copies of enrolled state; it is not hardware attestation. A malicious client that copies both credentials and session metadata cannot be distinguished by this mechanism. Exclude the entire enrollment state and spool from golden images and enroll each instance separately.

On the agent detail page, Reporting diagnostics holds past identity conflicts. A historical event alone requires no action. The Reporting attempts are being blocked warning appears when the same competing process keeps being refused for more than two minutes, its latest refusal is less than two minutes old, and another session still holds the lease.

Check for an extra RouteSpear process on the host or another device using copied enrollment credentials. Stop the extra process, or enroll each device separately. Allow up to two minutes for the previous lease to expire and reporting to resume. The warning clears when a fresh lease is granted, the lease expires, or refusals go quiet for two minutes; the last conflict remains in diagnostics. Renewals by the current lease holder do not prove the competing process has recovered.

Under Usage & budget, enable ephemeral fleet admission to stop expired instances consuming a permanent enrollment slot. Fresh registrations reserve capacity for five minutes before first reporting. Historical agent rows are retained; the system does not delete or archive them automatically. The tenant’s enrollment capacity and enrollment rate limits still apply. Enforced concurrent reporting capacity separately limits live leases across the account.

Upgrade agents before enabling enforcement. Older clients without reporting-session metadata are measured in compatibility mode while observation is enabled and refused when enforcement is enabled. The fleet activity panel remains a current-page inventory summary; the account usage screen reports account-wide live leases.

See usage and budget controls for minute reservations, caps and refusal behavior.

Connect endpoint tests to a desktop session

With an updated VDI host agent, the existing desktop-session collector also reads the remote client’s reported name and IPv4 address when the Windows desktop stack provides them. No new check needs to be scheduled. The endpoint only needs its normal private agent running in the same organization.

Open a desktop session’s Timeline → Session health. The server looks for an enabled private agent with an exact, case-insensitive inventory-name match and a report within 90 seconds of the session observation. Custom agent names must match the desktop client’s reported name for this initial detection method.

• Detected endpoint · unverified: exactly one recent agent matches. This is inferred evidence, not proof of who opened the desktop.
• Unconfirmed: multiple agents match. No endpoint is selected and no endpoint test data is attributed to the connection.
• Endpoint not identified: no qualifying match or no usable client name. An IP address by itself never establishes a match.

The reported address is displayed as supporting context. NAT, gateways, unavailable client metadata, and clients that report different names can prevent detection. This initial matcher does not claim an authenticated user or connection-destination match.

Disconnects, changes in client metadata or matching evidence, and observation gaps longer than 90 seconds create separate intervals. Earlier associations remain available, so reconnecting from another endpoint does not rewrite history. The view retains the latest 200 intervals and shows the currently reporting status of each side separately from its historical interval.

Each side offers its currently assigned tests and predefined headline metrics. Queries include that side’s agent ID, the chosen test ID, and the observed interval, bounded to 30 days. Existing measurements are reused; no additional probes are launched. Missing measurements remain missing, and historical test assignments are not reconstructed. Host resource links use the same interval. Agent-service checks run in the service’s context, not the user’s browser or authenticated desktop context.

Verified pairing is not implemented by name detection. It requires a desktop-platform integration that transports a short-lived challenge through the actual desktop connection and authenticates both enrolled agents independently. No detected connection is labeled verified.

Check for expected desktop sessions

Add a Desktop Sessions check under Host / workloads, assigned to the Windows session-host agent running as LocalSystem. Choose the platform explicitly; there is no automatic platform selection. Optionally enter an exact Windows user name (DOMAIN\user), an exact reported client computer name, and a minimum number of connected sessions. Names match without regard to case. Disconnected sessions do not satisfy the check. Leave both name filters blank to check the selected source across the host.

The selected source determines what the check looks for:

• Microsoft RDP / Azure Virtual Desktop: Windows sessions reporting RDP protocol type 2. This includes ordinary RDP and does not establish AVD broker membership. See Microsoft’s session information reference.
• Citrix ICA sessions: Windows session names beginning with ICA-, including the standard ICA-TCP and ICA-CGP names. This is a session-name heuristic, not a WFAPI or virtual-channel integration. Custom names are not matched. See Citrix’s ICA-CGP configuration reference.
• Omnissa Horizon: ViewClient_Machine_Name from the observed user’s Volatile Environment registry data. Session-specific data takes precedence; user-level data is used only when that user has one observed logon. Missing or unreadable data makes collection incomplete. Values can be stale or refer to the physical client across nested desktops, so they do not prove the immediate endpoint. See Horizon’s client information reference.

The check publishes collection readiness, matching connected-session count, and whether the minimum is met. Incomplete collection publishes readiness only, so missing access does not become a zero-session outage. Session IDs in the result use the same logon identities as desktop session reporting. These results can be selected in the session’s existing host-test charts; they do not create verified endpoint pairings or run probes as the desktop user.

This check requires an updated Windows agent and server. It does not turn on the separate -desktop-sessions history reporter or replace its WTS client-name matching with vendor metadata. Enable that reporter to use the Agents session timeline and correlated charts.