Windows Installation - KloudMate Agent

The KloudMate Agent for Windows provides a GUI-based installer that installs the agent as a Windows service for continuous monitoring of Windows systems.

System Requirements

Supported Operating Systems

Windows Server 2016 or later
Windows 10 (64-bit)
Windows 11 (64-bit)

Prerequisites

Administrator privileges
.NET Framework 4.5+ (usually pre-installed)
Network connectivity to KloudMate endpoints
API Key from KloudMate Settings

Installation Methods

Method 1: GUI Installer (Recommended)

Download Installer

Download the latest installer from the GitHub Releases page:

# Using PowerShell
Invoke-WebRequest -Uri "https://github.com/kloudmate/km-agent/releases/latest/download/kmagent-setup.exe" -OutFile "kmagent-setup.exe"

Or download directly from:

https://github.com/kloudmate/km-agent/releases/latest

Look for the file: kmagent-{version}-setup.exe

Run Installer

Right-click the installer and select “Run as Administrator”:

.\kmagent-setup.exe

Administrator privileges are required to install Windows services and write to protected directories.

Configure Installation

The installer will prompt for:

API Key (required): Your KloudMate authentication key
Collector Endpoint (required): Default is https://otel.kloudmate.com:4318

The wizard validates that required fields are not empty before proceeding.

Complete Installation

The installer will:

Install the kmagent.exe binary to C:\Program Files\KloudMate Agent\
Generate configuration file at C:\ProgramData\KloudMate Agent\agent.yaml
Create and start the Windows service named kmagent
Configure the service to start automatically on system boot

Verify Installation

Check that the service is running:

Get-Service kmagent

Expected output:

Status   Name               DisplayName
------   ----               -----------
Running  kmagent            KloudMate agent for OpenTelemetry

Method 2: Silent Installation

For automated deployments, use silent installation mode:

.\kmagent-setup.exe /SILENT /API_KEY="your-api-key" /COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318"

Parameters:

/SILENT - Run installer without GUI
/VERYSILENT - Completely silent (no progress window)
/API_KEY="..." - Set API key
/COLLECTOR_ENDPOINT="..." - Set collector endpoint
/DIR="C:\Custom\Path" - Custom installation directory
/LOG="install.log" - Create installation log

Example with logging:

.\kmagent-setup.exe /VERYSILENT /API_KEY="km_xxx" /COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318" /LOG="C:\Temp\kmagent-install.log"

Installation Details

Installed Components

The installer creates the following structure:

C:\Program Files\KloudMate Agent\
├── kmagent.exe           # Main executable
├── config.yaml           # Default OpenTelemetry configuration
└── unins000.exe          # Uninstaller

C:\ProgramData\KloudMate Agent\
└── agent.yaml            # Agent configuration (API key, endpoints)

Windows Service Configuration

The agent is installed as a Windows service with these properties:

Property	Value
Service Name	`kmagent`
Display Name	`KloudMate agent for OpenTelemetry`
Description	Monitors system metrics and logs using KMAgent
Startup Type	Automatic
Run As	Local System Account
Service Binary	`C:\Program Files\KloudMate Agent\kmagent.exe --agent-config "C:\ProgramData\KloudMate Agent\agent.yaml" start`

Configuration Files

Agent Configuration

Location: C:\ProgramData\KloudMate Agent\agent.yaml Generated during installation:

api-key: "your-api-key"
collector-endpoint: "https://otel.kloudmate.com:4318"

OpenTelemetry Configuration

Location: C:\Program Files\KloudMate Agent\config.yaml Contains the OpenTelemetry Collector pipeline configuration (receivers, processors, exporters).

Service Management

Using Services Console

Press Win + R
Type services.msc
Find “KloudMate agent for OpenTelemetry”
Right-click to Start, Stop, or Restart

Using PowerShell

# Check service status
Get-Service kmagent

# Start the service
Start-Service kmagent

# Stop the service
Stop-Service kmagent

# Restart the service
Restart-Service kmagent

# View service details
Get-Service kmagent | Format-List *

# Check if service is running
if ((Get-Service kmagent).Status -eq 'Running') {
    Write-Host "KM Agent is running"
}

Using Command Prompt (sc.exe)

# Query service status
sc query kmagent

# Start service
sc start kmagent

# Stop service
sc stop kmagent

# View service configuration
sc qc kmagent

# Change startup type to automatic
sc config kmagent start= auto

# Change startup type to manual
sc config kmagent start= demand

View Logs

Event Viewer

The agent logs to Windows Event Viewer:

Press Win + R
Type eventvwr.msc
Navigate to Windows Logs → Application
Filter by source: kmagent

PowerShell Event Log Query

# View recent agent events
Get-EventLog -LogName Application -Source kmagent -Newest 50

# View errors only
Get-EventLog -LogName Application -Source kmagent -EntryType Error -Newest 20

# Export logs to file
Get-EventLog -LogName Application -Source kmagent -Newest 100 | 
    Export-Csv -Path "C:\Temp\kmagent-logs.csv"

Application Log Files

If file logging is configured, check:

C:\ProgramData\KloudMate Agent\logs\

Updating the Agent

Download New Version

Download the latest installer from GitHub Releases.

Run New Installer

The installer will:

Detect the existing installation
Stop the running service
Replace the executable
Preserve your configuration files
Restart the service

.\kmagent-new-version-setup.exe

Verify Update

Check the version:

& "C:\Program Files\KloudMate Agent\kmagent.exe" version

Uninstallation

Method 1: Programs and Features

Open Control Panel → Programs → Programs and Features
Find KloudMate Agent
Click Uninstall
Follow the uninstall wizard

Method 2: PowerShell

# Find the uninstaller
$uninstaller = "C:\Program Files\KloudMate Agent\unins000.exe"

# Run silent uninstall
Start-Process -FilePath $uninstaller -ArgumentList "/SILENT" -Wait

Method 3: Manual Uninstall

Stop the Service

Stop-Service kmagent

Delete the Service

sc delete kmagent

Remove Files

Remove-Item -Path "C:\Program Files\KloudMate Agent" -Recurse -Force
Remove-Item -Path "C:\ProgramData\KloudMate Agent" -Recurse -Force

Clean Registry (Optional)

Remove registry entries under:

HKEY_LOCAL_MACHINE\SOFTWARE\KloudMate
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\{f0bcc1d7-e444-47ea-b6ce-18c671f5889d}

Installer Script Details

The Windows installer is built using Inno Setup. Key sections from the installer script:

Service Installation

function InstallService(): Boolean;
var
  ServicePath: String;
  ConfigPath: String;
  BinPath: String;
begin
  ServicePath := ExpandConstant('{app}\kmagent.exe');
  ConfigPath := ExpandConstant('{commonappdata}\kmagent\agent.yaml');
  BinPath := Format('"%s --agent-config "%s" start"', [ServicePath, ConfigPath]);
  
  // Create service
  sc create "kmagent" 
    binPath= <BinPath>
    start= auto 
    DisplayName= "Kloudmate Monitoring Service"
end;

Configuration Generation

function GenerateConfigFile(): Boolean;
var
  ConfigPath: String;
begin
  ConfigPath := ExpandConstant('{commonappdata}\kmagent\agent.yaml');
  
  ConfigLines.Add(Format('api-key: "%s"', [StoredAPIKey]));
  ConfigLines.Add(Format('collector-endpoint: "%s"', [StoredCollectorEndpoint]));
  
  ConfigLines.SaveToFile(ConfigPath);
end;

Service Management

The installer uses sc.exe commands for service management:

// Stop service
sc stop "kmagent"

// Delete service
sc delete "kmagent"

// Start service
sc start "kmagent"

Troubleshooting

Installer Fails with “Administrator Required”

Solution: Right-click installer and select “Run as Administrator”.

Service Fails to Start

Check Event Viewer:

Open Event Viewer (eventvwr.msc)
Navigate to Windows Logs → Application
Look for errors from source “kmagent”

Common causes:

Missing or invalid API key in C:\ProgramData\KloudMate Agent\agent.yaml
Invalid collector endpoint
Network connectivity issues
Port conflicts (4317, 4318)

Validate configuration:

Get-Content "C:\ProgramData\KloudMate Agent\agent.yaml"

Configuration File Not Found

Check if file exists:

Test-Path "C:\ProgramData\KloudMate Agent\agent.yaml"

Manually create:

New-Item -Path "C:\ProgramData\KloudMate Agent" -ItemType Directory -Force
Set-Content -Path "C:\ProgramData\KloudMate Agent\agent.yaml" -Value @"
api-key: "your-api-key"
collector-endpoint: "https://otel.kloudmate.com:4318"
"@

Service Crashes on Startup

Test manually:

cd "C:\Program Files\KloudMate Agent"
.\kmagent.exe --agent-config "C:\ProgramData\KloudMate Agent\agent.yaml" start

Check output for specific errors.

Network Connectivity Issues

Test endpoint:

Test-NetConnection -ComputerName otel.kloudmate.com -Port 4318

Check firewall:

Get-NetFirewallRule | Where-Object {$_.DisplayName -match "kmagent"}

Add firewall rule if needed:

New-NetFirewallRule -DisplayName "KloudMate Agent" -Direction Outbound -Program "C:\Program Files\KloudMate Agent\kmagent.exe" -Action Allow

Permission Errors

Check service account:

(Get-WmiObject Win32_Service -Filter "Name='kmagent'").StartName

Grant permissions to config directory:

$acl = Get-Acl "C:\ProgramData\KloudMate Agent"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule("SYSTEM","FullControl","ContainerInherit,ObjectInherit","None","Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\ProgramData\KloudMate Agent" $acl

Silent Install Fails

Check log file:

Get-Content "C:\Temp\kmagent-install.log"

Verify parameters:

.\kmagent-setup.exe /? # Show help

Building the Installer (Advanced)

For developers who want to build the installer from source:

Prerequisites

Inno Setup 6+ installed
Go 1.24.4+ for building the executable
Docker (for build environment)

Build Process

From the repository root:

# Build Windows executable
make build-windows

# Build installer
make build-installer

This creates:

dist/win/kmagent-{version}-setup.exe

Makefile Targets

build-windows:
	@echo "Building kmagent for Windows..."
	mkdir -p dist/win
	GOOS=windows CGO_ENABLED=0 go build -tags windows \
	  -ldflags="-s -w -X main.version=$(VERSION)" \
	  -o dist/win/kmagent.exe ./cmd/kmagent

build-installer: build-windows
	cp build/windows/installer.iss dist/win/installer.iss
	docker run --rm \
	  -v $(PWD):$(CONTAINER_WORKDIR) \
	  -w $(CONTAINER_WORKDIR) \
	  amake/innosetup:64bit-bookworm \
	  /dMyAppVersion=$(VERSION) "dist/win/installer.iss"

Next Steps

Configure Agent

Customize OpenTelemetry receivers and processors

Verify Installation

Confirm telemetry is flowing to KloudMate

Support

For Windows installation issues:

📧 Email: [email protected]
🐛 GitHub: Report an issue
📝 Event Logs: Check Windows Event Viewer for “kmagent” source

Getting Started

Installation

Configuration

Features

Architecture

Operations

​System Requirements

​Supported Operating Systems

​Prerequisites

​Installation Methods

​Method 1: GUI Installer (Recommended)

​Method 2: Silent Installation

​Installation Details

​Installed Components

​Windows Service Configuration

​Configuration Files

​Agent Configuration

​OpenTelemetry Configuration

​Service Management

​Using Services Console

​Using PowerShell

​Using Command Prompt (sc.exe)

​View Logs

​Event Viewer

​PowerShell Event Log Query

​Application Log Files

​Updating the Agent

​Uninstallation

​Method 1: Programs and Features

​Method 2: PowerShell

​Method 3: Manual Uninstall

​Installer Script Details

​Service Installation

​Configuration Generation

​Service Management

​Troubleshooting

​Installer Fails with “Administrator Required”

​Service Fails to Start

​Configuration File Not Found

​Service Crashes on Startup

​Network Connectivity Issues

​Permission Errors

​Silent Install Fails

​Building the Installer (Advanced)

​Prerequisites

​Build Process

​Makefile Targets

​Next Steps

Configure Agent

Verify Installation

​Support

Build docs developers (and LLMs) love

System Requirements

Supported Operating Systems

Prerequisites

Installation Methods

Method 1: GUI Installer (Recommended)

Method 2: Silent Installation

Installation Details

Installed Components

Windows Service Configuration

Configuration Files

Agent Configuration

OpenTelemetry Configuration

Service Management

Using Services Console

Using PowerShell

Using Command Prompt (sc.exe)

View Logs

Event Viewer

PowerShell Event Log Query

Application Log Files

Updating the Agent

Uninstallation

Method 1: Programs and Features

Method 2: PowerShell

Method 3: Manual Uninstall

Installer Script Details

Service Installation

Configuration Generation

Service Management

Troubleshooting

Installer Fails with “Administrator Required”

Service Fails to Start

Configuration File Not Found

Service Crashes on Startup

Network Connectivity Issues

Permission Errors

Silent Install Fails

Building the Installer (Advanced)

Prerequisites

Build Process

Makefile Targets

Next Steps

Support