Skip to main content

Install on Windows

Prerequisites​

  • Windows Server 2016+ (64-bit)
  • PowerShell 5.1 or higher
  • certutil.exe and certreq.exe present (default on Windows Server)
  • Outbound TCP 443 connectivity to the CLM
  • Service account with the necessary permissions on AD CS

Service account​

For use with AD CS, the agent's service account needs:

RequirementDescription
Member of Domain UsersDoes not need local administrator
Request Certificates on the CATo submit CSRs
Read on the CA and templatesTo list and download certificates
Enroll on the target templatesTo issue certificates with each template
Log on as a serviceIf running as a Windows service
Read/write on C:\clm-agent\For logs and configuration
Agent on the same server as AD CS
If the agent is installed on the AD CS server itself, the service account already has local access to the CA and the configuration is simpler. In production, it's recommended to keep the agent on a separate server.
  1. Go to Agents in the sidebar menu
  2. Click Install Agent
  3. On the Quick Install tab, fill in:
    • Agent Name — unique identifier for this agent, e.g.: prod-server-01
    • Run agent under a service account — check this option if using it with AD CS
    • Service account — enter the account in the format DOMAIN\service-user or service-user@domain.local
    • Service account password — optional on Windows; if left blank, it will be requested interactively on the server (more secure)
  4. Click Generate Pairing Code
  5. Copy the generated command and run it in an elevated PowerShell session on the target server

The script automatically performs:

  • Download of the clm-agent.exe binary
  • Creation of the C:\clm-agent\config.yaml file
  • Registration as a Windows Scheduled Task (CLMAgent)
  • Automatic start of the agent

After a few seconds, the agent will appear with Online status on the Agents screen.

If you fill in the password in the form, it will be embedded in the command and visible in the PowerShell history. For greater security, leave the field blank and enter the password interactively when prompted on the server.

Manual installation (offline environments)​

Use this method when the target server has no internet access during installation.

1. Create the agent in the CLM

Go to Agents → Install Agent → Quick Install, fill in the name and click Generate Pairing Code. Save the generated token — it is shown only once.

2. Download the binary

On the Manual Setup tab, download the executable for the server's architecture:

  • clm-agent-windows-amd64.exe (~7 MB) — for x64 servers
  • clm-agent-windows-arm64.exe (~6 MB) — for ARM64 servers

Transfer the file to the server via SCP, USB, or an internal mirror.

3. Prepare the directory

New-Item -ItemType Directory -Path 'C:\clm-agent' -Force | Out-Null
Move-Item -Path .\clm-agent-windows-<arch>.exe -Destination 'C:\clm-agent\clm-agent.exe' -Force

4. Create the configuration file

Save it as C:\clm-agent\config.yaml:

server:
  url: "wss://SEU-DOMINIO-CLM/api/agent/connect"
  token: "agent_COLE_O_TOKEN_AQUI"

agent:
  name: "nome-do-servidor"
  heartbeat_interval: 30
  reconnect_delay: 5
  max_reconnect_delay: 300

5. Register as a Scheduled Task

Run in elevated PowerShell:

$action = New-ScheduledTaskAction -Execute 'C:\clm-agent\clm-agent.exe' `
  -Argument '--config C:\clm-agent\config.yaml' `
  -WorkingDirectory 'C:\clm-agent'
$trigger = New-ScheduledTaskTrigger -AtStartup
$principal = New-ScheduledTaskPrincipal -UserId 'SYSTEM' -RunLevel Highest
$settings = New-ScheduledTaskSettingsSet -RestartCount 999 `
  -RestartInterval (New-TimeSpan -Minutes 1) `
  -ExecutionTimeLimit (New-TimeSpan -Hours 0)
Register-ScheduledTask -TaskName 'CLMAgent' -Action $action -Trigger $trigger `
  -Principal $principal -Settings $settings
Start-ScheduledTask -TaskName 'CLMAgent'

Managing the agent​

Run in an elevated PowerShell session on the server:

Check status

Get-ScheduledTask -TaskName 'CLMAgent' | Get-ScheduledTaskInfo

Start

Start-ScheduledTask -TaskName 'CLMAgent'

Stop

Stop-ScheduledTask -TaskName 'CLMAgent'

Restart

Stop-ScheduledTask -TaskName 'CLMAgent'; Start-Sleep -Seconds 2; Start-ScheduledTask -TaskName 'CLMAgent'

View logs in real time

Get-Content 'C:\clm-agent\agent.log' -Tail 50 -Wait

Rotate token

Generate a new token on the agent's row in Agents → Rotate Token, update config.yaml, and restart:

notepad 'C:\clm-agent\config.yaml'
Stop-ScheduledTask -TaskName 'CLMAgent'; Start-ScheduledTask -TaskName 'CLMAgent'

Uninstall

Stop-ScheduledTask -TaskName 'CLMAgent' -ErrorAction SilentlyContinue
Unregister-ScheduledTask -TaskName 'CLMAgent' -Confirm:$false
Remove-Item -Path 'C:\clm-agent' -Recurse -Force
note
Uninstalling the agent from the server does not remove its registration in the CLM. Use the **Delete** action on the agent's row under **Agents** to also remove the record from the platform.