Install the CloudSmith Agent

The CloudSmith Agent is a Windows Service that runs on each Hyper-V host you want to manage. It connects to the CloudSmith Relay over TCP port 8443, enrolls once on first boot, then heartbeats every 30 seconds, polls for jobs, and pushes hardware and cluster inventory every 5 minutes.

Install the agent on every Windows Server host that CloudSmith should have visibility into or control over.

Prerequisites

• Windows Server 2019, 2022, or 2025
• .NET 9 Runtime — or use the self-contained agent binary (no runtime required; see Step 2)
• Network access from the host to the relay host on TCP port 8443
• Local administrator or SYSTEM rights (required to install a Windows Service)
• The relay LAN IP address and the RELAY_AGENT_ENROLLMENT_TOKEN value you set on the relay

If you have not yet deployed the relay, complete Install the CloudSmith Relay first.

Step 1 — Note your relay LAN IP and agent secret

You will need two values from the relay setup:

• Relay LAN IP — the IP address of the Linux host running the relay container. Agents connect to http://<relay-lan-ip>:8443. There is no TLS on the LAN side of the relay at this version.
• RELAY_AGENT_ENROLLMENT_TOKEN — the shared secret you chose when deploying the relay. This is the value agents present to enroll.

Confirm the relay is reachable from the Hyper-V host before proceeding:

Test-NetConnection -ComputerName <relay-lan-ip> -Port 8443

Expected output: TcpTestSucceeded : True. If connectivity fails, check host-based firewalls on both the relay host and the Windows Server host before continuing.

Step 2 — Download the agent binary

Download the agent binary from the CloudSmith GitHub releases page:

$releaseUrl = 'https://github.com/cloudsmith-cloud/cloudsmith-agent/releases/latest/download/cloudsmith-agent.exe'
$dest       = 'C:\CloudSmith\cloudsmith-agent.exe'

New-Item -ItemType Directory -Path 'C:\CloudSmith' -Force | Out-Null
Invoke-WebRequest -Uri $releaseUrl -OutFile $dest

The self-contained binary includes the .NET 9 runtime — no separate runtime installation is required when using the self-contained build. Check the release notes for your version to confirm whether the download is framework-dependent or self-contained.

Step 3 — Install the Windows Service

Run the following commands in an elevated PowerShell session:

# Create the service
sc.exe create CloudSmithAgent `
    binPath="C:\CloudSmith\cloudsmith-agent.exe" `
    start=auto `
    DisplayName="CloudSmith Agent"

# Set a description
sc.exe description CloudSmithAgent "CloudSmith managed host agent — connects to relay and executes platform jobs."

Set environment variables via registry

The agent reads its configuration from Windows Service environment variables stored in the registry. Set them now, before starting the service:

$regPath = 'HKLM:\SYSTEM\CurrentControlSet\Services\CloudSmithAgent\Environment'

# Create the registry key if it doesn't exist
New-Item -Path $regPath -Force | Out-Null

# Required variables
New-ItemProperty -Path $regPath -Name 'AGENT_RELAY_URL'          -Value 'http://<relay-lan-ip>:8443' -PropertyType String -Force
New-ItemProperty -Path $regPath -Name 'AGENT_ENROLLMENT_TOKEN'   -Value '<your-relay-agent-secret>'  -PropertyType String -Force

# Optional variables — defaults shown; omit to accept defaults
New-ItemProperty -Path $regPath -Name 'AGENT_SCAN_INTERVAL_SECONDS' -Value '300'                                          -PropertyType String -Force
New-ItemProperty -Path $regPath -Name 'AGENT_CLUSTER_ID'             -Value 'default'                                     -PropertyType String -Force
New-ItemProperty -Path $regPath -Name 'AGENT_IDENTITY_PATH'          -Value 'C:\ProgramData\CloudSmith\agent-identity.json' -PropertyType String -Force
New-ItemProperty -Path $regPath -Name 'AGENT_INSTALL_DIRECTORY'      -Value 'C:\CloudSmith'                                -PropertyType String -Force

Replace <relay-lan-ip> and <your-relay-agent-secret> with the values from Step 1.

All environment variables

Step 4 — Start the service and verify enrollment

Start the service:

sc.exe start CloudSmithAgent

Check service state:

sc.exe query CloudSmithAgent

Expected output includes STATE: 4 RUNNING.

Check the Windows Event Log

The agent writes enrollment and connection events to the Windows Event Log under the source CloudSmith:

Get-EventLog -LogName Application -Source CloudSmith -Newest 20

On a successful first enrollment you will see an event with message text similar to:

Agent enrolled: AgentId=agent-01hz... RelayUrl=http://192.168.1.10:8443
Agent heartbeat running. Polling interval: 30s. Scan interval: 300s.

Verify in the portal

In the CloudSmith portal, navigate to Operations → Hosts. The host should appear within 30–60 seconds of the agent starting. Confirm the status shows as Connected.

Repeat on each managed host

Run Steps 2–4 on every Hyper-V host you want CloudSmith to manage. Each host connects independently to the relay using the same AGENT_RELAY_URL and AGENT_ENROLLMENT_TOKEN. The relay issues a unique agentId + agentSecret to each host during enrollment.

Troubleshooting

Service starts but immediately stops (State: STOPPED). Check the Windows Event Log for the error detail:

Get-EventLog -LogName Application -Source CloudSmith -EntryType Error -Newest 5

The most common cause is a missing or malformed registry key. Confirm all required variables are present under HKLM:\SYSTEM\CurrentControlSet\Services\CloudSmithAgent\Environment.

Event Log shows "enrollment token rejected" or "relay returned 401". The AGENT_ENROLLMENT_TOKEN value does not match RELAY_AGENT_ENROLLMENT_TOKEN on the relay. Verify both values are identical — no leading or trailing whitespace.

Event Log shows "connection refused" or "relay unreachable". The relay host or port 8443 is not reachable. Run Test-NetConnection -ComputerName <relay-lan-ip> -Port 8443 from the affected host. Check Windows Firewall on the relay’s Linux host (ufw, iptables) and any network-layer firewall rules between the subnet and the relay host.

Host appears in portal but shows stale inventory. The agent is connected but the scan interval has not elapsed. Wait up to AGENT_SCAN_INTERVAL_SECONDS (default 5 minutes) for the first full inventory push. You can force an immediate scan from the portal: Operations → Hosts → (select host) → Refresh inventory.

Service will not start after a relay restart. After a relay restart, agents reconnect and re-enroll automatically on their next heartbeat cycle (within 30 seconds). No manual intervention is required. The agent’s enrolled identity (AGENT_IDENTITY_PATH) is separate from the relay’s enrolled identity — agents do not need the original AGENT_ENROLLMENT_TOKEN for reconnection, only the persisted identity file.

Next steps

• All managed hosts are visible under Operations → Hosts once enrolled.
• To register a Hyper-V Failover Cluster, navigate to Operations → Clusters → Register a cluster and select the hosts you enrolled.
• For additional agent configuration, see Configuration reference — agent environment variables.