Install the CloudGrange Agent
The CloudGrange Agent is a Windows service that runs on each Hyper-V host you want to manage. It connects to the site's relay, enrolls once, then heartbeats, polls for jobs, and pushes hardware and cluster inventory.
Install the agent on every Windows Server host that CloudGrange should see or control.
CloudGrange is in active development and is not GA. The agent code lives in cloudgrange-runtime-agent. See current product and release status.
Prerequisites
- Windows Server (2019, 2022, or 2025) with the Hyper-V role for hosts you intend to manage
- Network access from the host to the relay on TCP 8443
- Local administrator / SYSTEM rights (required to install a Windows service)
- The relay address and the
RELAY_AGENT_ENROLLMENT_TOKENvalue set on the relay
If you have not deployed a relay yet, complete Install the CloudGrange Relay first. (In the default on-premises install the relay is already part of the stack.)
Confirm the relay is reachable before proceeding:
Test-NetConnection -ComputerName <relay-host> -Port 8443
# Expected: TcpTestSucceeded : True
Install
The agent installs via Install-Agent.ps1 from cloudgrange-runtime-agent, which creates and configures the Windows service. The service reads its configuration from environment variables (stored for the service in the registry). The required and common optional variables:
| Variable | Required | Description |
|---|---|---|
AGENT_RELAY_URL |
Yes | Relay LAN endpoint — https://<control-plane-host>:8443 for every on-premises install. On the Kubernetes/Helm paths this is the relay's Service on 8443; on the legacy Compose stack nginx terminates TLS and proxies to the relay. The address and port are the same either way. |
AGENT_ENROLLMENT_TOKEN |
Yes (first start) | The relay's RELAY_AGENT_ENROLLMENT_TOKEN. Consumed on enrollment; the agent persists its own identity afterward. |
AGENT_CLUSTER_ID |
No | Cluster this host belongs to (default default). |
AGENT_SCAN_INTERVAL_SECONDS |
No | Inventory push interval (default 300). |
AGENT_IDENTITY_PATH |
No | Where the agent persists its enrolled identity. |
AGENT_INSTALL_DIRECTORY |
No | Install root; ACL-hardened to SYSTEM + Administrators. |
The agent never sends secrets to diagnostics:
AGENT_ENROLLMENT_TOKENand anyAGENT_SECRET_*values are redacted from health and diagnostic output.
Verify
After installation, confirm the service is running and enrolled:
Get-Service CloudGrangeAgent
The agent appears under the site's relay in the portal once enrollment completes. Job execution, inventory, and heartbeat then flow through the relay.
If the agent does not appear, check the relay side. On the Kubernetes/Helm paths:
sudo k3s kubectl logs -l app.kubernetes.io/name=cloudgrange-relay --tail=100
sudo k3s kubectl get svc -l app.kubernetes.io/name=cloudgrange-relay
On the legacy Compose stack:
sudo docker compose -f /opt/cloudgrange/docker-compose.yml logs --tail=100 cloudgrange-relay
The most common causes are a firewall blocking inbound 8443 to the relay, and an AGENT_ENROLLMENT_TOKEN that does not match the relay's RELAY_AGENT_ENROLLMENT_TOKEN.