Server Agent Deployment via GPO

The Kabeen server agent can be centrally deployed across all your Windows servers using Microsoft Active Directory Group Policy Objects (GPO).

Deployment happens in two stages, both fully native to Group Policy: installing the MSI package through Software installation, then distributing the configuration file through the Files preference.

New in 3.0. The agent no longer reads any registry key. Its entire configuration lives in a single config.toml file, reloaded automatically every 10 seconds. If an older Kapsul agent is present on the machine, its API key and identifier are migrated automatically on first start (see Migrating from the legacy agent).

Prerequisites

• Administrative rights on the domain controller
• Windows servers joined to the domain (Windows Server 2016+, Windows 10/11)
• The signed MSI package: kabeen-server-agent-<version>-x86_64.msi (-aarch64.msi variant for ARM machines)
• A Kabeen API key
• Outbound connectivity to intake.kabeen.io on port 443/TCP

Download the package from your Kabeen console (Infrastructure > Add a server > Automatic installation) or directly:

Step 1: Prepare the network share

1. Create a shared folder accessible by all target servers.
2. Copy the MSI file into it.
3. Check the permissions: since the installation runs in machine context, it is the computer accounts that need read access (through Authenticated Users or Domain Computers), not user accounts.

\\fileserver.corp\software$\Kabeen\kabeen-server-agent-x86_64.msi

The path must be a UNC path: a local path (C:\...) would not resolve from the target servers.

Step 2: Create the installation GPO

1. Open the Group Policy Management console (GPMC).
2. Create a new GPO linked to the OU containing your servers.
3. Edit the GPO and navigate to:
   • Computer Configuration > Policies > Software Settings > Software installation
4. Right-click > New > Package.
5. Select the MSI file from the UNC network path.
6. Choose Assigned as the deployment method.

Installation is triggered at the server's next reboot, in machine context, before logon. It copies the binary to C:\Program Files\Kabeen\Server Agent\, registers the KabeenServerAgent Windows service (automatic start) and starts it.

No API key has been supplied at this point, and that is expected: the service starts anyway and waits for a valid configuration, logging Configuration is incomplete (api_key is empty). Waiting.... It does not crash and consumes virtually no resources. The key is distributed in the next step.

Step 3: Distribute the configuration

In 3.0 the API key is no longer configured through a registry key: it is read from C:\ProgramData\Kabeen\Server Agent\config.toml. The simplest approach is to distribute a central reference file through Group Policy Preferences.

Prepare the reference config.toml

Place a config.toml file on your share containing:

# Kabeen Server Agent configuration
api_key = "YOUR_KABEEN_API_KEY"
 
# Uncomment only if needed:
# proxy = "http://proxy.corp.example:8080"
# network_usage = false

These three keys — plus endpoint, which should only be changed on support instruction — are all the settings the agent recognises.

Encoding. The file must be saved as UTF-8 without BOM (not UTF-16): wrong encoding prevents the agent from starting. Reliable methods and diagnostics in Diagnostics › Configuration file encoding.

Protect this file. It contains the API key in clear text: restrict the share ACLs to read access for Domain Computers only.

Create the GPO preference

1. In the same GPO, navigate to:
   • Computer Configuration > Preferences > Windows Settings > Files
2. Right-click > New > File.
3. Fill in:
   • Action: Replace (or Update if you would rather not overwrite a local customisation)
   • Source file(s): \\fileserver.corp\software$\Kabeen\config.toml
   • Destination file: C:\ProgramData\Kabeen\Server Agent\config.toml

No service restart is required. The agent re-reads config.toml every 10 seconds: the configuration is picked up on the next tick, including when you rotate the key later on.

Restrict the permissions of the dropped file

The Files preference copies the ACLs inherited from C:\ProgramData. To lock the file down, add an immediate task to the GPO (see variant B) running:

icacls "C:\ProgramData\Kabeen\Server Agent\config.toml" /inheritance:r `
    /grant "SYSTEM:(F)" `
    /grant "Administrators:(F)" `
    /grant "NT SERVICE\KabeenServerAgent:(R)"

This same Files preference also lets you update the API key across an already-equipped fleet, without reinstalling anything.

Step 4: Apply and verify

1. Force a policy refresh on a test server, then reboot it to trigger the installation:

gpupdate /force
Restart-Computer

2. After the reboot, verify the service is running:

Get-Service -Name KabeenServerAgent

3. Check the agent logs:

Get-Content "C:\ProgramData\Kabeen\Server Agent\logs\$(Get-Date -Format 'yyyy-MM-dd').log" -Tail 30

Once a valid API key is picked up, the logs should show All tasks running. Agent is operational. and the machine should appear in your Kabeen console with a recent heartbeat (less than 2 minutes).

Variants

Variant A: MST transform carrying the API key

The MSI exposes a public APIKEY property, usable from the command line:

msiexec /i "kabeen-server-agent-x86_64.msi" /qn /norestart APIKEY="YOUR_KABEEN_API_KEY"

Since the Software installation GPO offers no "arguments" field, the only way to inject that property is an .mst transform file, declared in the package's Modifications tab (only available if you pick Advanced rather than Assigned when creating the package).

Generate the MST with Orca (Windows SDK): Transform > New Transform, Property table, add a row APIKEY = your key, then Transform > Generate Transform.

Two important limitations before choosing this variant:

• The API key ends up in clear text inside the .mst stored on the share. Apply the same restrictive ACLs as on config.toml.
• On installation the MSI rewrites config.toml in full with only the API key. When you later upgrade the package with the same MST, any proxy or network_usage you had added would therefore be lost. This variant is not recommended if you go through a proxy.

Variant B: immediate task and PowerShell script

This approach installs and configures in a single pass, with no prior reboot, and handles the ACLs correctly.

Create an immediate task in the GPO:

• Computer Configuration > Preferences > Control Panel Settings > Scheduled Tasks > New > Immediate Task (At least Windows 7)
• User: NT AUTHORITY\System
• Run with highest privileges: checked
• Action: Start a program
  • Program: powershell.exe
  • Arguments: -NoProfile -ExecutionPolicy Bypass -File "\\fileserver.corp\software$\Kabeen\install.ps1"

Contents of install.ps1 (adapt it, and sign it if your policies require it):

$ErrorActionPreference = 'Stop'
$msi    = '\\fileserver.corp\software$\Kabeen\kabeen-server-agent-x86_64.msi'
$marker = 'C:\ProgramData\Kabeen\Server Agent\.gpo-installed'
$apiKey = '<KEY_RETRIEVED_FROM_YOUR_VAULT>'
 
if (Test-Path $marker) { exit 0 }   # already installed by the GPO
 
# 1. Silent installation
Start-Process msiexec.exe -ArgumentList @(
    '/i', "`"$msi`"", '/qn', '/norestart',
    '/l*v', 'C:\Windows\Temp\kabeen-server-agent-install.log'
) -Wait -NoNewWindow
 
# 2. Configuration
$cfgDir = 'C:\ProgramData\Kabeen\Server Agent'
$cfg    = Join-Path $cfgDir 'config.toml'
[System.IO.File]::WriteAllText($cfg, "api_key = `"$apiKey`"`n", `
    (New-Object System.Text.UTF8Encoding $false))   # UTF-8 without BOM
icacls $cfg /inheritance:r `
    /grant 'SYSTEM:(F)' `
    /grant 'Administrators:(F)' `
    /grant 'NT SERVICE\KabeenServerAgent:(R)' | Out-Null
 
# 3. Idempotency marker
New-Item -ItemType File -Path $marker -Force | Out-Null

Never store the key in clear text in the script. Prefer retrieving it from an internal vault (Azure Key Vault, HashiCorp Vault) at execution time.

Also note that the APIKEY property appears in clear text in a verbose /l*v log: protect or purge those files.

Security group filtering

For a gradual rollout:

1. Create a security group holding the target computer accounts (e.g. "Kabeen-Agent-Servers").
2. In the GPO, Delegation tab > Advanced.
3. Remove "Authenticated Users" from application (uncheck Apply group policy).
4. Add your group with "Read" and "Apply group policy" rights.

Updating the fleet

The MSI uses a stable UpgradeCode and a major upgrade: the new version installs over the old one, preserving both the configuration and the host identity.

1. Place the new MSI on the share.
2. In the GPO, create a new package and, in its Upgrades tab, declare that it replaces the previous package.

Since the C:\ProgramData\Kabeen\Server Agent folder is marked permanent, config.toml also survives an uninstall. See Updating the server agent and Uninstalling the server agent.

Migrating from the legacy agent

If an older Kapsul agent is already installed on the target servers, the server agent imports its configuration automatically on the very first start:

Carrying over the agentUUID guarantees the machine keeps the same identity in the Kabeen console — it does not show up as a new host.

Migration happens only once and never overwrites an already-populated configuration. On a fleet being migrated you can therefore roll out the installation GPO without distributing a config.toml: each server will pick up its own existing key. Recommended procedure: deploy the server agent, confirm in the console that machines report under the same identifier, then uninstall the legacy agent.

Troubleshooting

Installation does not start

• Verify the UNC path is reachable from the computer account (not from your admin session).
• Verify read permissions on the share and on the MSI file.
• A reboot is mandatory to trigger an Assigned installation: gpupdate /force alone is not enough.
• Check the Windows event logs (Application and System) and the output of gpresult /h report.html.

The service runs but nothing shows up in the console

This is almost always a configuration issue:

• Verify that C:\ProgramData\Kabeen\Server Agent\config.toml exists and contains api_key.
• The key must be at least 16 characters long and must not be a filler value (changeme, placeholder…): otherwise the agent treats the configuration as incomplete and waits.
• Verify the file encoding: UTF-8 without BOM.
• The log message Configuration is incomplete (api_key is empty). Waiting... confirms this diagnosis.

Connection error

• Test outbound connectivity: Test-NetConnection -ComputerName intake.kabeen.io -Port 443.
• Check the firewall: only outbound 443/TCP to intake.kabeen.io is required.
• Behind a corporate proxy, refer to Proxy configuration for the server agent.