> For the complete documentation index, see [llms.txt](https://docs.nuvens.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nuvens.cloud/install/workspaces-manager-agent.md).

# WorkSpaces Manager Agent

{% hint style="warning" %}
**Recommended for Full Functionality:** The WSM Agent requires **.NET 4.6.2** or above. Ensure that this version or a later version of .NET is installed on the WorkSpace to enable all features of the WSM Agent.
{% endhint %}

The **WSM Agent** collects information related to both user activity and WorkSpace metrics. The latest version of the WSM Agent installer is always available at the following URL:

<https://nuvensworkspacesmanager.s3.eu-west-1.amazonaws.com/latest/WSMAgent.msi>

For the agent to function correctly, certain **registry key values** must be configured so that the agent can identify and connect to the **Management Portal API**. An example of the required registry key format is shown below. The keys are structured as follows:

```
[HKEY_USERS\.DEFAULT\Software\Nuvens]
"Portal"="https://portal.nuvens.co"
"Frequency"=dword:00000005
"Visible"="true"
"IdleMinutes"=dword:0000000f
"DisconnectOnIdle"="false"
"LiveBroadcastEnabled"="true"
"LiveBroadcastFrequencyMs"=dword:00001388
"LiveHubUrl"="https://portal.nuvens.co/hubs/livestats"
"RunElevated"="false"
```

***

The Portal value specifies the location of the **WorkSpaces Manager Portal** and the protocol used to access it. This value should be defined as a URL and can reference either an **IP address** or a **DNS hostname**. For example:

```
"Portal"="https://portal.nuvens.co"
```

{% hint style="danger" %}
After deployment, update the **Portal** value in the registry key file with the **IP address** or **DNS name** of your WorkSpaces Manager Portal. Ensure that the correct protocol (**HTTP or HTTPS**) is specified, according to the configuration of your WorkSpaces Manager Portal.
{% endhint %}

***

The "**Frequency**" value specifies how often the **WSM Agent** reports metrics to the WorkSpaces Manager Portal. This value is expressed in **minutes**. For example:

```
"Frequency"=dword:00000005
```

This means the agent reports every **5 minutes**.

{% hint style="info" %}
In environments with a large number of WorkSpaces, increasing this value can help reduce database load and improve overall system performance. For earlier versions of the WSM Agent (version 5), a legacy attribute named "**UpdateFrequency**" was used for the same purpose.
{% endhint %}

***

The "**Visible**" value determines whether the WSM Agent icon is displayed in the Windows system tray. This value accepts true or false. For example:

```
"Visible"="true"
```

When set to "**true**", the WSM Agent icon is visible in the **system tray**, allowing users or administrators to easily verify that the agent is running.

When set to "**false**", the icon is hidden from the system tray. However, the WSM Agent continues to run normally in the background. Its execution can still be verified in Task Manager, where it appears as a process named **WSMAgent**.

***

The "**IdleMinutes**" value defines the number of **minutes of user inactivity** before the WorkSpace is considered idle by the WSM Agent. For example:

```
"IdleMinutes"=dword:0000000f
```

This means the agent will treat the session as idle after **15 minutes** of inactivity.

***

The "**DisconnectOnIdle**" value controls whether the agent should trigger a disconnect action when the session becomes idle. This value accepts true or false. For example:

```
"DisconnectOnIdle"="false"
```

When set to "**true**", the agent will disconnect the session after the configured idle threshold is reached. When set to "**false**", the session remains active even if the user is marked as idle.

***

To enable **Live Stats** (Real-Time Metrics) and **Startup Metrics**, the following additional registry values must be configured:

```
"RunElevated"="true"
"LiveBroadcastEnabled"="true"
"LiveBroadcastFrequencyMs"=dword:00001388
"LiveHubUrl"="https://portal.nuvens.co/hubs/livestats"
```

The "**LiveBroadcastFrequencyMs**" value controls how frequently these metrics are sent to the portal, expressed **in milliseconds**.

"**LiveHubUrl**" must use **HTTPS** with a trusted certificate. Where TLS is terminated at a load balancer, the WorkSpaces Manager Portal must recognise HTTPS through its trusted reverse proxy configuration.

The **RunElevated** value allows the WSM Agent to collect **Startup Metrics**, which require elevated privileges. The agent must be run through a **Windows Scheduled Task** in the user context with elevated privileges.

To prevent multiple instances of the agent from running, remove **WSMAgent.lnk** from the Common Startup folder (`shell:common startup`). The agent should then be started exclusively through the Scheduled Task.

When enabled, **Live Stats** provide visibility into login performance, including **profile loading**, **GPO processing**, **Windows shell readiness**, and **overall login duration**. Live Stats also report running processes and their **CPU and memory usage**.

An example of **Startup Metrics** and process information is shown below:

<figure><img src="https://1977539604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5qADNWBPym2Zh4ZaguCE%2Fuploads%2FIUCiNZ0TzcPNcb13C6MO%2Fimage.png?alt=media&amp;token=b5b49a57-4819-4891-9e7e-068eca1d3933" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
If **Startup Metrics** are required, additional configuration is necessary to modify how the agent is started. Instead of launching from the **Windows Startup folder**, the agent must be configured to run as a **Scheduled Task at user logon**.

Running the agent as a Scheduled Task allows it to start with the highest privileges, enabling the collection of startup and login performance metrics without granting elevated permissions to the user.

For detailed configuration steps, refer to the [**GPO Scheduled Task Setup**](https://docs.nuvens.cloud/install/appendices/gpo-scheduled-task-setup.md).
{% endhint %}

***

From **WSM Agent 6.4.1**, the agent can report live process usage to WorkSpaces Manager. To allow administrators to terminate processes on **WorkSpaces Applications**, additional configuration is required.

{% hint style="info" %}
To terminate a process, the administrator must be a **SuperAdmin** or have the role `Permissions.AppStream.EndProcess`
{% endhint %}

On each **WorkSpaces Manager instance**, create the system environment variable:

<pre><code><strong>LiveAgentCommands__SharedKey
</strong></code></pre>

Generate the shared key once using PowerShell:

```powershell
$bytes = New-Object byte[] 32
$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rng.GetBytes($bytes)
$rng.Dispose()
[Convert]::ToBase64String($bytes)
```

{% hint style="warning" %}
The **same key** must be configured on every WorkSpaces Manager instance.
{% endhint %}

On each WorkSpace running the **WSM Agent**, add the following registry value using the same key:

```
"LiveCommandKey"="<shared-key>"
```

{% hint style="danger" %}
The value of `LiveCommandKey` must match `LiveAgentCommands__SharedKey` configured on the WorkSpaces Manager instances.
{% endhint %}

***

There are several ways to deploy the registry settings on your WorkSpaces. Some common methods include:

* **Add Manually to Golden Images**: Apply the registry settings directly to your golden images, ensuring that all cloned WorkSpaces inherit the correct configurations.
* **Group Policy (GPO)**: Distribute the registry settings via [Group Policy (GPO) using Active Directory](https://docs.nuvens.cloud/install/appendices/gpo-and-values-for-workspaces-manager-agent.md), which automates the process for all WorkSpaces in the domain.
* **Microsoft Intune (Entra ID Hybrid)**: Use Intune to distribute the registry settings when managing devices with Entra ID Hybrid for centralized control.
* **Distribution Tool (e.g., SCCM)**: Leverage distribution tools like System Center Configuration Manager (SCCM) to push registry settings across your WorkSpaces fleet.
* **AWS Systems Manager**: Use the AWS Systems Manager Run Command or State Manager to push the registry settings across your fleet of WorkSpaces.
* **PowerShell Scripts**: Create a PowerShell script that modifies the registry with the required values.
* **Logon Scripts**: Add a registry modification script to the logon process of the WorkSpaces, ensuring that each user gets the settings applied upon login.
* **Configuration Management Tools**: Use tools like **Chef**, **Puppet**, or **Ansible** to automate the deployment of registry settings across WorkSpaces.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nuvens.cloud/install/workspaces-manager-agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
