Agents

The VirtualMetric Agent is a lightweight service that collects telemetry from Windows and Linux endpoints and forwards it to a Director or Cluster for processing and routing.

Introduction

Agents provide local log collection with optional edge-based pre-processing. They connect to Directors or Clusters using token-based authentication and support automatic configuration synchronization.

Agent vs Agentless

DataStream supports two deployment approaches for Windows and Linux endpoints. Both approaches install a collector agent on the endpoint; they differ in how the installation is initiated and how credentials are managed.

Aspect	Agent	Agentless
Initiation	User runs script on endpoint	Director connects to endpoint remotely
Installation	Script installs and starts collector	Director installs and starts collector
Initial connection	Endpoint connects TO Director/Cluster	Director connects TO endpoint
Protocol	HTTPS (outbound from endpoint)	WinRM (Windows) / SSH (Linux)
Credential handling	Token-based (no credentials in UI)	User credentials stored on Director
Pre-processing	Full pipeline support at edge	Full pipeline support at edge
Buffering	Local store-and-forward	Local store-and-forward
Network resilience	User re-establishes after interruptions	Director restarts after interruptions
Orchestrated Director support	Yes	No (Agentless is disabled when an Orchestrated Director is selected)

Supported Platforms

Platform	Agent	Agentless	Protocol
Windows	Yes	Yes	WinRM
Linux	Yes	Yes	SSH

Architecture

Agents collect logs locally on the endpoint and forward them to the Director:

The Agent authenticates using a token issued by the Director or Cluster. Configuration changes made in the Director interface synchronize automatically to connected Agents.

Deployment

Agent Deployment

Agent deployment installs the VirtualMetric Agent binary on the endpoint. The installation process:

1. Create Device: In the Setup Device step of the creation wizard, set the device name and select the target Director. When the selected Director has defined access tokens, a Token dropdown also appears in this step for selecting which token the Agent will use. See Management for full wizard details.
2. Run Installation Script: Execute the provided PowerShell (Windows) or Bash (Linux) script on the endpoint
3. Verify Connection: Confirm the Agent has connected successfully

The wizard provides platform-specific installation scripts (actual commands provided by wizard):

PowerShell

$h="<config-token>"; iwr directorip/dl | iex

Bash

curl -sL directorip/dl | sudo h="<config-token>" director="directorip" bash

After installation, the Agent service starts automatically and connects to the Director or Cluster.

To enroll many Windows or Linux Agents at once with shared approval rules, naming, datasets, and update policy, use an Enrollment Template instead of running the installation script per endpoint.

Agentless Deployment

Agentless deployment allows the Director to install and start the collector agent remotely without manual script execution on the endpoint. The Director connects using the credentials provided in the UI:

• Windows: WinRM (Windows Remote Management) on port 5985
• Linux: SSH on port 22

The Install and Connect step of the wizard exposes platform-specific credential fields:

Windows Agentless — connects over WinRM with Windows credentials:

• IP Address and Port for the target host
• Active Directory Authentication checkbox to use the current AD context instead of explicit credentials
• Username and Password — both support entering a value manually, referencing an environment variable, or referencing a secret from the Vault
• Domain (optional) — Windows domain for the supplied credentials

Linux Agentless — connects over SSH with either password or key-based authentication:

• IP Address and Port for the target host
• Timeout (optional) — SSH connection timeout in seconds
• SSH Key checkbox — toggles authentication between password and SSH key
• When SSH Key is enabled: SSH Key content field, plus an optional SSH Key Passphrase
• When SSH Key is disabled: Username and Password fields

Orchestrated Director restriction

When an Orchestrated Director is selected in the Setup Device step, Agentless deployment is automatically disabled. The wizard shows an info alert explaining that orchestrated mode only supports Agent deployment.

Once connected, the Director installs the collector service on the remote machine and starts it. The collector then operates identically to an Agent deployment, collecting logs locally and forwarding them to the Director.

For agentless configuration details, see the Windows and Linux device documentation.

Director vs Cluster Connection

Agents can connect to either a standalone Director or a Cluster. For Cluster configuration and management, see Directors: Clusters. For Director TLS configuration and automatic CA bootstrap, see Transport Layer Security.

Director Connection: The Agent connects to a single Director instance. If the Director fails, the Agent buffers data locally until the connection is restored. This simpler configuration suits single-site deployments.

Cluster Connection: The Agent connects to the Cluster as a whole rather than to individual Directors. Any healthy Director in the Cluster can receive Agent data, providing automatic failover if one Director becomes unavailable. This approach is recommended for production deployments requiring high availability.

Management

Agent devices are managed through the Devices web interface at Home > Fleet Management > Devices. Select Windows or Linux from the device categories.

For complete GUI documentation including the creation wizard, detail view tabs, data configuration options, and device operations, see Devices: Management.

Pre-Processing

Agents can execute pipeline-based pre-processing before transmitting data to the Director. This distributed processing model reduces Director workload and network bandwidth.

Processing Flow

With Pre-Processing:

1. Agent Collection - Agent collects logs locally at endpoint
2. Agent Processing - Agent executes configured pipeline transformations
3. Agent Transmission - Agent sends pre-processed data to Director
4. Director Routing - Director forwards data to targets

Without Pre-Processing:

1. Agent Collection - Agent collects logs locally at endpoint
2. Agent Transmission - Agent sends raw data to Director
3. Director Processing - Director executes pipeline transformations
4. Director Routing - Director forwards processed data to targets

Pipeline Assignment

Pre-processing pipelines run inside the datasets that an Agent is configured to collect. Pipelines are not assigned directly per log type on the device — they are part of each dataset's definition. The Agent's data collection is configured in the wizard's Review & Configure Data step, and later edited from the device detail view's Data Configuration tab, by choosing one of two configuration modes:

• Datasets — Pick individual dataset types to collect. Each dataset definition specifies the source log type and any pre-processing pipeline that runs on its data.
• Profiles — Apply a profile that bundles multiple dataset selections together, for consistent collection across many endpoints.

See Datasets and Profiles for the full configuration model.

Pipelines assigned to Agents (via the datasets they collect) use the same syntax as Director pipelines, and all processor types are available for Agent execution. Configuration is managed centrally through the Director interface, with changes synchronizing automatically to connected Agents.

Windows DCR Collection

On Windows endpoints, the Agent supports event collection via Azure-compatible Data Collection Rules (DCRs). The device detail view exposes an Import DCR Config action that accepts a DCR XPath query and registers a corresponding event collector on the Agent. See Devices: Management for the wizard and tab details.

Auto Update

Agents support automatic updates when new versions become available. The Agent downloads updates from its managing Director and includes built-in rollback capability with cryptographic signature verification.

Configuration

Auto Update is configured through the update section in the Agent configuration:

Property	Type	Required	Description
mode	string	Y	Set to auto to enable automatic updates
method	string	Y	Update trigger method: immediate or schedule
version	string	Y	Target version to update to
cron	string	N	Cron expression for scheduled updates (schedule method only, minimum 30 seconds)
interval	duration	N	Fallback polling interval if no cron specified (default: 30s minimum)

Example Configuration:

update:
  mode: auto
  method: schedule
  version: "2.5.0"
  cron: "0 3 * * *"  # Daily at 3:00 AM

Update Methods

Immediate Method:

Triggers the update as soon as possible after configuration is applied. A 10-minute cooldown prevents rapid retry attempts if the update fails.

update:
  mode: auto
  method: immediate
  version: "2.5.0"

Schedule Method:

Updates occur according to a cron schedule or interval-based polling. Use cron expressions for precise scheduling or configure an interval for periodic checks.

update:
  mode: auto
  method: schedule
  version: "2.5.0"
  interval: 1h  # Check hourly

Update Process

When an update triggers, the Agent performs these steps:

1. Version Check - Compares current version against configured target version
2. Service Stop - Gracefully stops the running Agent service
3. Backup - Creates timestamped backup of current binary and configuration
4. Download - Retrieves new binary from the managing Director
5. Signature Verification - Verifies Ed25519 signature of downloaded binary
6. Deployment - Replaces current binary with new version
7. Service Start - Restarts the Agent service

If any step fails, the rollback system automatically restores the previous binary and configuration.

note

Unlike Directors, Agents only update the service binary. Package resources (pipelines, definitions) are managed centrally on the Director and synchronized to Agents automatically.

Health Reporting

During an update, the Agent reports additional health information to its managing Director:

Field	Description
version	Currently running Agent version
scheduled_version	Target version pending update
architecture	System architecture (amd64, arm64, etc.)
os	Operating system (windows, linux)

The scheduled version field appears in health reports after an update is triggered but before it completes, allowing administrators to track pending updates across the Agent fleet.

Security

Agent Auto Update includes the same security measures as Director updates:

• Ed25519 Signature Verification: All downloaded binaries are verified against cryptographic signatures before deployment
• Secure Download: Binaries are downloaded over HTTPS from the managing Director
• Rollback Protection: Failed updates automatically restore the previous working version

warning

Auto Update requires network connectivity to the managing Director. Ensure the Agent can reach the Director's update endpoint for binary downloads.

Troubleshooting

Connection Issues

Agent Not Connecting:

• Verify network connectivity between endpoint and Director
• Check firewall rules allow outbound connections
• Confirm the token has not expired
• Verify Director/Cluster is running and accessible

Connection Drops:

• Agent buffers data locally during connectivity interruptions
• Data transmits automatically when connection restores
• Check network stability and latency

Authentication Failures:

• Verify token is valid and not expired
• Confirm token is assigned to correct Director/Cluster
• Regenerate token if necessary

Agentless Connection Issues

WinRM Connection Failed (Windows):

• Verify WinRM service is running on target
• Check port 5985 is accessible
• Confirm credentials have required permissions
• For domain auth, verify domain trust relationships

SSH Connection Failed (Linux):

• Verify SSH service is running on target
• Check port 22 is accessible
• Confirm username/password or key authentication
• Verify user has required permissions for log access

Advanced Troubleshooting

For detailed Agent diagnostics and CLI operations, see the Agent CLI Reference.