The ControlUp Automation module includes the Install-CUAgent PowerShell cmdlet which allows you to download and install a ControlUp Agent on your local machine. You can either download the agent binaries from the ControlUp Cloud or from a local ZIP file. To install a non-domain joined agent on a workgroup machine, you must provide an API authentication token (API Key) generated from app.controlup.com (DEX).
To uninstall the agent from your local machine, use the Uninstall-CUAgent cmdlet. To update an agent, see Invoke-CUAgentUpdate.
Depending on your organization's infrastructure and deployment preferences, ControlUp offers several flexible methods to deploy the agent across your environment:
Deployment Method | When to Use |
|---|---|
Best for automation pipelines, bulk provisioning, CI/CD workflows, and scripted golden‑image preparation. Gives full control and repeatability for large‑scale deployments. Installs agent on a machine with no need to use the Real-Time DX Console. | |
Best for centralized, automated deployment and updates across domain‑joined VDI machines. To learn how to add machines remotely, watch video. | |
Best for offline, non‑domain, image‑based installs, or restricted environments using an enterprise software distribution tool (SCCM, GPO, PDQ). Manual, silent installation. |
API Registration Key
If you provide the API Key with the Install-CUAgent cmdlet, it adds the agent machine to your organization tree in the Real-Time DX Console. By default, the cmdlet returns whether the agent was successfully installed or not.
From ControlUp version 9.0.5 and higher, you can use agent self-registration with either PowerShell cmdlets or our MSI to add the agent machine to your organization tree. For versions lower than 9.0.5, you must use the Console to manually add the agent machine to your organization tree.
Benefits
Download and install agents with no need to use the Real-Time DX Console.
Install the MSI directly without using the ZIP file.
Install agents on workgroup machines.
Automatically register and connect agents to monitors.
Prerequisites
Real-Time DX Console Version 9.0 or higher.
If your organization already exists in the Real-Time DX Console, the user you use to install the agent must be a Roles Manager.
If your organization doesn’t exist in the console, you must be assigned the DEX Admin role for permission to deploy agents.
For machine requirements, see here.
Syntax
Install-CUAgent -Token <string> -InstallationDirectory <string> -FolderPath <string> -InstallAgentManager <boolean> -Site <string> -BrokeringMode <Online/Offline> -MonitorFQDNs <string> -ProxyToControlUpBackend <string> -ProxyToMonitor <string> -ZipFilePath <string> -Version or -Latest <string> -ProxySettings <ProxySettingsObject> -AgentRegistrationKey <string> -AgentPort <Int32> -AgentAuthenticationKey <string> -InstallAsMasterImage <boolean> -AddFirewallRule <boolean> -ConnectionType <string> -Debug <string>
Parameters
Parameter | Description | Required |
|---|---|---|
Token string (API Key) generated by web UI for authentication and authorization. If provided, | Only if | |
-AgentAuthenticationKey | Public key to authorize inbound connections to the agent. You can copy the key from the Real-Time Console (Settings > Agent > Agent Authentication Key) or by running the Get-AgentPublicKey cmdlet on your monitor machine. | Only if |
-AgentRegistrationKey | Public key to authorize outbound connections from the agent to the monitors. You can copy the key from the Real-Time Console (Settings > Agent > Agent Registration Key) or by running the Get-AgentRegistrationKey cmdlet on your monitor machine. | Only for agent outbound connections, and if |
-AddFirewallRule | Adds an inbound firewall rule to the agent service. | No |
-AgentPort | Sets port for an inbound agent. By default, 40705. | No |
-BrokeringMode | If set to | No |
-ConnectionType | Sets the agent communication to monitors as an | No |
-Debug | Enables agent debugging. | No |
-FolderPath | If provided with an API Key, the folder path in your organization tree to add the agent to. If provided, but the specified folder doesn't exist, it gets created. If not provided, the latest agent uploaded to the cloud will be installed and added to your root folder. Note that | No |
-InstallationDirectory | If provided, you can define a custom installation folder for the agent file. If not provided, the default installation folder will be used. Note that | No |
-InstallAgentManager | This optional parameter will be available to use in an upcoming release. | No |
-InstallAsMasterImage | Relevant only for outbound agents, installs the agent machine as a master image. Not supported for agent self-registration. | No |
-Latest | Switch parameter for -Version, latest agent version. If provided, overrides -Version. | No |
-ProxySettings | Proxy settings that the ControlUp Automation module will use to download the Agent binaries and register the Agent. If not provided, the default system proxy settings will be used. | No |
-ProxyToControlUpBackend | Proxy connection to ControlUp backend. | No |
-ProxyToMonitor | Proxy connection that the agent will use to connect to the monitor services. | No |
-Site | Assigns a ControlUp Monitor site name from your organization to the Agent. If not provided, the default site will be used. If you provide a site name that doesn’t exist, the installation fails. | No |
-Version | Switch parameter for -Latest, agent version. If not provided, the latest version will be downloaded as a ZIP file from the cloud. | No |
-ZipFilePath | Full path to the ZIP folder that contains the ControlUp Agent binaries. If not provided, -Version will be used, and the agent version you specified from the cloud will be installed. | No |
Install Agent on a Local Machine
To install a ControlUp Agent on a local machine, follow the steps below.
1. Open a PowerShell session with elevated permissions and install the module by running the following:
Install-Module ControlUp.AutomationThe module is automatically imported.
2. Install the agent:
Install-CUAgent
-Token "[APIKey]" or -AgentAuthenticationKey "[Authentication Key]" -AgentRegistrationKey "[Registration Key]" Example:
Install-CUAgent
-Token "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MjEwNDIzNDcsImlhdCI6MTcI..."Install Agent with Self-Registration
To install an agent using self-registration, follow the steps below.
1. Open a PowerShell session with elevated permissions and install the module by running the following:
Install-Module ControlUp.AutomationThe module is automatically imported.
2. Install the agent and provide the following required parameters:
Install-CUAgent
-Token "[APIKey]"
-Site "[SiteName]"
-FolderPath "[FolderPathName]"
-Version "[VersionNumber]"
Example:
Install-CUAgent
-Token "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MjEwNDIzNDcsImlhdCI6MTcI..."
-Site "NYC office"
-FolderPath "EmployeeSeven\NewFolder"
-Version "9.0.5.423"In the example above, the agent is automatically added to the organization tree in the folder "NewFolder" and assigned to the site "NYC office." By default, the agent connects outbound to the monitor in the assigned site.
Uninstall-CUAgent
Uninstalls the ControlUp Agent from your local machine. If you run the cmdlet with an API Key, it also removes the agent from your organization tree.
Syntax
Uninstall-CUAgent
-Token <string>
-Force <string>
-Debug <string>
-RemainOnOrgTree <string>Parameters
Parameter | Description | Required |
|---|---|---|
-Token | Token string (API Key) generated by web UI for authentication and authorization. | No |
-Force | Uninstalls the agent even if backend errors occur. | No |
-Debug | Enables agent debugging. | No |
-RemainOnOrgTree | If provided, the agent remains in your organization tree after you uninstall it. | No |