--- title: "Install-CUMonitor: Install a Monitor" slug: "install-cumonitor" updated: 2026-05-01T07:15:27Z published: 2026-05-01T07:15:27Z canonical: "support.controlup.com/install-cumonitor" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.controlup.com/llms.txt > Use this file to discover all available pages before exploring further. # Install-CUMonitor: Install a Monitor The [ControlUp Automation module](https://www.powershellgallery.com/packages/ControlUp.Automation) includes the **Install-CUMonitor** PowerShell cmdlet which allows you to install a ControlUp Monitor programmatically on machines in your organization. To install a monitor, you must provide an [API Key](/v1/docs/create-an-api-key) generated from [app.controlup.com](http://app.controlup.com). Note that installing the monitor with the Automation module automatically installs the ControlUp Agent, and also self-registers the Agent in your organization. ## Benefits - **Automated Deployment:** Script-driven installation enables consistent, repeatable monitor deployments across multiple machines without manual configuration. - **Cloud and Workgroup Support:** Install monitors on workgroup machines, cloud VMs, and isolated environments without domain connectivity requirements. - **Zero-Touch Installation:** Fully automated process from binary download to service registration - no manual steps required after running the command. - **Built-in Error Handling:** Automatic rollback on failure and detailed error reporting for troubleshooting deployment issues. - **Infrastructure as Code:** Integrate monitor deployment into CI/CD pipelines, Infrastructure as Code workflows, and automated provisioning scripts. - **Consistent Configuration:** Ensure all monitors are deployed with identical settings, reducing configuration drift and human errors. - **Version Control:** Specify exact monitor versions for controlled deployments and easy rollback scenarios. ## Prerequisites - ControlUp.Automation module 1.0.4 or higher (Previous versions will likely fail) - If your organization already exists in the Real-Time DX Console, the user who installs the monitor 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 monitors. Note that running **Install-CUMonitor** automatically bootstraps a new Real-Time DX organization. The name of this organization will be the same as in DEX. ### Syntax ```plaintext Install-CUMonitor -Token -ZipFilePath -Version -SiteName -Template -ProxySettings -DomainDns -DomainUser -DomainUserPassword -PublicDNSName or -InternalDNSName -Certificate -CertificatePassword ``` ### Parameters | Parameter | Description | Required | | --- | --- | --- | | [-Token](/v1/docs/create-an-api-key) | Token string (API Key) generated by web UI for authentication and authorization. If not provided, the current profile's API Key will be used. For more cmdlets to manage API Keys, see [here](/tim-reorg/docs/90-powershell-cmdlets#manage-api-tokens). | Yes | | -ZipFilePath | Full path to the ZIP folder that contains the ControlUp Monitor binaries. If not provided, -Version will be used. | No | | -Version | Full name of the monitor version. If not provided, the latest monitor version is used. | Yes, if no - latest version used | | -SiteName | Name of the monitor site. If not provided, the monitor will be added to the default site. | No | | -Template | Name to define the [monitor template](/v1/docs/90-powershell-cmdlets#changecumonitortemplate). Available templates include: - all - backup_coordinator - broker_only coordinator - datanode - folderagg - monitoring - management - gateway (viewnode) - monitoring_only - indexing_only If empty, the selected template will be **all**. | No | | -ProxySettings | Proxy settings that the monitor will use to connect to the ControlUp services. If not provided, the default system proxy settings will be used. If -SiteName is provided, the proxy settings and credentials will be added to the specific site, if no proxy settings already exist. Example to create proxy settings variable: ```powershell $Secure = Read-Host -AsSecureString $proxys = New-Object -TypeName ControlUp.Automation.ProxySettings $proxys.Password=$Secure $proxys.sProxyAddress="127.0.0.1" $proxys.iProxyPort=80802 $proxys.Auth=No $proxys.User=Admin7 $proxys.Domain=myorg.com ``` | No | | -DomainDns | If provided and no AD connection already exists in the domain, the AD connection will be added with the -DomainUser and -DomainUserPassword credentials. If -SiteName is provided, the AD connection and credentials are added to the specific site. | No | | -DomainUser | Domain user name. If not provided, the AD connection won’t be added. | No | | -DomainUserPassword | Domain user password. If not provided, the AD connection won’t be added. Example to create password variable: ```powershell $Pwd = Read-Host -AsSecureString ``` | No | | -PublicDNSName | External endpoint for outbound agent connections | Yes, if no -InternalDNSName | | -InternalDNSName | Internal cluster communication between monitors | Yes, if no -PublicDNSName | | -Certificate | Path to the certificate file (.pfx or *.cer) required for [Advanced Authentication](/v1/docs/certificate-based-console-and-monitor-authentication). Only needed if your organization requires certificate-based authentication and the certificate is not already installed in **Local Machine > Personal certificates**. If a monitor is already installed and running on a workgroup machine, use the workaround [here](/v1/docs/certificate-based-console-and-monitor-authentication#update-certificate-for-workgroup-monitor) to enable Advanced Authentication. | Conditional | | -CertificatePassword | Secure string containing the password for the certificate private key. Required when using the -Certificate parameter | Conditional | ### Install Monitor on a Machine To install a monitor on a machine, follow the steps below. These steps should be executed on the machine where you intend to deploy the monitor. 1. Open a PowerShell session with elevated permissions and install the module: ```powershell      Install-Module ControlUp.Automation     ``` 2. Import the module: ```powershell      Import-Module ControlUp.Automation     ``` 3. Install the monitor: ```powershell Install-CUMonitor  -Token "[API Key]"  -PublicDNSName "[Machine Name].[Connection-specific DNS Suffix]"  -InternalDNSName "[Machine Name].[Connection-specific DNS Suffix]"     ``` Example: ```powershell Install-CUMonitor  -Token "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3Mzc5NzY0NjEsImlhdCI6MTcwNjQ0…."  -PublicDNSName "PSMonitor01.4rgvsyeccjuujimhr5m1ljkc.bx.internal.cloudapp.net"  -InternalDNSName "PSMonitor01.4rgvsyeccjuujimhr5m1ljkc.bx.internal.cloudapp.net" ``` If you want to deploy other monitors, repeat steps 1-3. Stop Workgroup Monitor Note that if you want to stop a workgroup monitor, you must run the [**Stop monitor** action](/v1/docs/90-actions-for-controlup-monitor-management#run-monitor-actions) on the monitor in the web UI. You can't use the Real-Time DX Console to stop a workgroup monitor. If you want to deploy a monitor with custom manual settings, we recommend you use the following script as a base to create your own: ```powershell Install-CUMonitor -Token "[API Key]" -InternalDNSName "[Machine Name].[Connection-specific DNS Suffix]" ``` ### Results Writes single result object to PowerShell with the following properties: - Error. In case of failure, the reason will be displayed. - Success. Indicates if the monitor installation and login completed successfully. In case of failure during the installation, all the changes will be canceled. In case of failure during login, the changes will be implemented. If these cases occur, you can uninstall the monitor by running [Uninstall-CUMonitor](/v1/docs/90-powershell-cmdlets#uninstallcumonitor).