Deploying the Relay client on Windows

Deploy the Relay client as a Windows Service to establish an outbound tunnel between your network and Test Cloud.

This page covers production setup details specific to Windows. For cross-platform prerequisites and network requirements, see Deploying the Relay client.

Operating system requirements

The Relay client uses the Windows Service Control Manager (SCM) to install and manage its background service. SCM is built into all supported Windows versions. No additional software is required.

Edition	Minimum version
Windows Server	2019
Windows Desktop	10 Enterprise

Additional requirements

• PowerShell 5.1+: included by default; used for service management (Get-Service, Test-NetConnection). Verify: $PSVersionTable.PSVersion.
• Administrator privileges: required to interact with SCM for service installation, start, stop, and deletion; write to C:\ProgramData\UiPathRelay\; copy the binary to C:\Program Files\UiPathRelay\.

By default the service runs as LocalSystem. To run under a specific account, use --service-account at start time. See Service account and permissions.

Prerequisites

System

• Windows Server 2019+ or Windows 10 Enterprise+
• PowerShell 5.1 or later
• Administrator access to the target machine
• Minimum 200 MB free disk space
• If you use a supported TCP-based connection that requires the on-prem executor:
  • Review the recommended host and executor capacity
  • A Java 21 or later JRE or JDK, either on the PATH or passed with --onprem-executor-java-home. An existing installation works.

Network

• For Relay client 26.4.2 or later, outbound HTTPS (port 443) to cloud.uipath.com is allowed, including WebSocket upgrades
• For Relay client versions earlier than 26.4.2, outbound TLS (port 443) to <region>-relay.uipath.com is allowed and TLS passthrough is configured
• Relay host can resolve and connect to every registered HTTP or HTTPS endpoint, and to the host and port of each supported TCP-based endpoint

Security

• Service account created (if not using LocalSystem) (see Service account and permissions)
• Windows Defender and antivirus exclusions planned (see Antivirus and endpoint protection)
• If you use the on-prem executor: a connector dependencies directory and a Java runtime, both in locations only administrators can modify, such as under C:\Program Files. The executor loads code from both

Configuration

• Relay Group created and client configuration string ready (see Configuring a Relay group)

Validate prerequisites

Run the following commands in PowerShell:

# Check PowerShell version (must be 5.1+)
$PSVersionTable.PSVersion

# Verify Administrator access
([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

# Check available disk space
Get-PSDrive C | Select-Object Used, Free

# On-prem executor only: Java 21+ on PATH, or pass --onprem-executor-java-home
java -version

Install

1. Download and extract

Download the Relay client archive for your architecture (x86_64 or ARM64) from the UiPath Customer Portal.

Extract the zip archive. Starting with Relay client 26.4.3, it contains relay.exe and onprem-executor.jar. Leave both files together in the extracted directory, and run installation or upgrade commands from that directory.

2. Start

Open PowerShell as Administrator before running any start command.

You can provide the client configuration string (generated in UiPath Administration, as described in Configuring a Relay group) in two ways:

Option A: Inline. Pass the configuration string directly. No file to create or clean up:

.\relay.exe start --config "<your-config>" --accept-license-agreement

Option B: File. Save the configuration to a file, then reference it. This is the recommended option because it keeps the secret out of shell history:

Set-Content -Path ".\config.txt" -Value "<your-config>"
.\relay.exe start --config-file ".\config.txt" --accept-license-agreement

For a supported TCP-based connection that requires the on-prem executor, stage the connector libraries first, as described in Add connector dependencies, then start the client with a single command.

Add connector dependencies

Some connectors require third-party libraries that are not included with the Relay client. Obtain them from the connector vendor and place them all in a dedicated directory on the Relay host. The Relay client stores the directory path but does not copy the libraries. A directory under C:\Program Files, such as C:\Program Files\UiPathRelay\executor-deps, is writable only by administrators by default.

Important:

The on-prem executor loads and executes these libraries with the permissions of the Relay service account. Use a durable directory that the service account can read and that is writable only by administrators. Anyone who can modify its contents can run code with those permissions.

For SAP BAPI, obtain the SAP JCo 3 libraries from SAP and place these files in the dependency directory:

Required file	Purpose
sapjco3.jar	SAP JCo Java library
sapidoc3.jar	SAP IDoc Java library
sapjco3.dll	SAP JCo Windows native library matching the Java runtime architecture

For another supported connector, place the vendor libraries listed in that connector's documentation in the same directory.

Start with the on-prem executor

Create the dependency directory, copy the libraries into it, and start the Relay client with the executor enabled. Point --onprem-executor-java-home at a Java 21 or later runtime installed under C:\Program Files, so the executor uses the runtime you intend:

.\relay.exe start --config-file ".\config.txt" `
  --accept-license-agreement `
  --enable-onprem-executor `
  --onprem-executor-java-home "C:\Program Files\Java\jdk-21" `
  --onprem-executor-dep-dir "C:\Program Files\UiPathRelay\executor-deps"

Note:

The --config and --config-file flags are mutually exclusive. To run in the foreground instead of as a background service (useful for debugging), pass --detach=false.

The Relay client validates connectivity, authenticates with OAuth, registers with Test Cloud, downloads proxy configuration, and installs a Windows service, all in a single command.

Expected output:

Running prerequisite checks...
  ✓ Directory permissions: OK
  ✓ Cloud portal connectivity: OK
✓ All prerequisite checks passed
Waiting for service to start...
  ✓ Service is running

✓ Relay is now running in the background.
Check status:
  PowerShell: Get-Service "Relay-<id>"
  Services:   services.msc (look for "Relay - <id>")

Note:

During startup, the Relay client automatically copies the binary to C:\Program Files\UiPathRelay\relay.exe. All relay groups on the machine share this single binary. Override the install directory with --bin-dir.

To start under a custom service account instead of LocalSystem:

.\relay.exe start --config-file C:\path\to\config.txt `
  --accept-license-agreement `
  --service-account "DOMAIN\svc-relay" `
  --service-account-password "<password>"

3. Verify

.\relay.exe list

A healthy client shows ● running in the STATUS column. The ID value shown is used in all subsequent commands (.\relay.exe stop <id>, .\relay.exe logs <id>, and so on). You can also find it in UiPath Administration under the relay group details page.

Confirm the tunnel is established by checking the logs for login to server success:

.\relay.exe logs <id> -f

If the on-prem executor is enabled, confirm its configuration:

.\relay.exe describe <id>

The On-Prem Executor section reports Enabled: true with the listen port, runtime version, runtime path, Java home, and dependencies directory it is using. Check that the Java home and dependencies directory are the ones you intended.

Then confirm that the executor started. Its log contains a Started OnPremRuntimeApplication entry once it is ready:

Select-String -Path "C:\ProgramData\UiPathRelay\logs\<id>\onprem-executor.log" -Pattern "Started OnPremRuntimeApplication"
Get-Content "C:\ProgramData\UiPathRelay\logs\<id>\onprem-executor.log" -Tail 20

If you configured a custom log directory, use its onprem-executor.log path instead. Then run a test call from the connector that uses this endpoint, to confirm the full path works.

Manage

All management commands require Administrator PowerShell, except list and version.

List

Shows all installed relay groups on this machine with status, version, and group name when available. Does not require Administrator privileges.

.\relay.exe list
.\relay.exe list --json

Describe

Note:

Available with Relay client 26.4.2 and later. Run .\relay.exe version to check your installed version.

Shows detailed information for one relay group, including service settings, configured paths, status, version, and group name when available. Does not require Administrator privileges.

.\relay.exe describe <id>
.\relay.exe describe <id> --json

Stop

Stops the relay service. Configuration and logs are retained. The relay can be restarted later.

.\relay.exe stop <id>

Restart and upgrade

Restarts the relay service and fetches the latest proxy configuration from Test Cloud.

.\relay.exe restart <id>

Upgrade: extract the new Relay client archive. Keep the new relay.exe and matching onprem-executor.jar together, then run .\relay.exe restart <id> from the extracted directory. The restart command updates the installed binary and, when the executor is enabled, its JAR.

To enable the executor on a service that is already installed, run .\relay.exe restart <id> --enable-onprem-executor from the extracted archive directory, so the matching onprem-executor.jar is available.

Scenario	Command
Endpoints added or removed in Test Cloud	.\relay.exe restart <id>
Client secret rotation (inline)	.\relay.exe restart --config "<new-config>"
Client secret rotation (file)	.\relay.exe restart --config-file new-config.txt
Log level change	.\relay.exe restart <id> --log-level debug
Log directory or retention change	.\relay.exe restart <id> --logs-dir "D:\MyCompany" --log-retention-days 30
Enable the on-prem executor	.\relay.exe restart <id> --enable-onprem-executor
Disable the on-prem executor	.\relay.exe restart <id> --disable-onprem-executor
Relay client upgrade	Extract the new archive, then run .\relay.exe restart <id>

Note:

When --config or --config-file is provided, the <id> argument is optional. It is extracted from the configuration.

Delete

Stops the service, deregisters from Test Cloud, and removes all local configuration and log files.

.\relay.exe delete <id>

To force local cleanup without cloud deregistration, for example if credentials are lost or the cloud-side relay group has already been deleted:

.\relay.exe delete <id> --force

Version

.\relay.exe version

Note:

There is no auto-upgrade. Extract the new archive and run .\relay.exe restart <id> from its directory for each group.

Directory structure

All directories are created automatically on first run.

C:\Program Files\UiPathRelay\
  relay.exe                                  # Shared binary

C:\ProgramData\UiPathRelay\
  groups\<id>\
    client_config                            # OAuth credentials (encrypted via DPAPI)
    metadata.json                            # State, PID, install timestamps
    .credentials.key                         # Encryption key
    onprem-executor.jar                      # Executor runtime when enabled
  logs\<id>\
    relay.log                                # Current log
    relay.YYYYMMDD-HHMMSS.log                # Rotated logs
    onprem-executor.log                      # Executor log when enabled

The Windows service name is Relay-<id> and the display name (shown in services.msc) is Relay - <id>. Startup type is Automatic; default account is LocalSystem.

Custom paths

Override the default directories when installing the Relay client.

.\relay.exe start --config-file C:\path\to\config.txt `
  --accept-license-agreement `
  --bin-dir "D:\MyCompany\bin" `
  --data-dir "D:\MyCompany" `
  --logs-dir "D:\MyCompany"

Flag	Default	Description
--bin-dir	C:\Program Files\UiPathRelay	Directory for the shared binary
--data-dir	C:\ProgramData	Root for configuration data
--logs-dir	C:\ProgramData	Root for log files; can be changed with restart

The Relay client appends UiPathRelay\ under the custom data and log roots:

--bin-dir  D:\MyCompany\bin  =>  D:\MyCompany\bin\relay.exe
--data-dir D:\MyCompany      =>  D:\MyCompany\UiPathRelay\groups\<id>\
--logs-dir D:\MyCompany      =>  D:\MyCompany\UiPathRelay\logs\<id>\

Note:

--bin-dir and --data-dir are only accepted by the start command. --logs-dir is accepted by start and restart. Other commands (stop, delete, list) discover paths automatically from the installed service configuration.

Service account and permissions

This section applies only when running the service under a custom account instead of the default LocalSystem.

Required user rights

Right	Description	How to configure
SeServiceLogonRight	Log on as a service	Local Security Policy > User Rights Assignment > Log on as a service

For domain environments, configure this right via Group Policy to ensure consistency across servers.

NTFS permissions

Path	Required permissions
C:\Program Files\UiPathRelay\	Read & Execute
C:\ProgramData\UiPathRelay\	Read, Write, Modify
C:\ProgramData\UiPathRelay\logs\	Read, Write, Modify, Delete
Dependencies directory (executor only)	Read & Execute, and not writable by unprivileged users. Inherited from C:\Program Files by default
Java installation (executor only)	Read & Execute, and not writable by unprivileged users

Via PowerShell

$account = "DOMAIN\svc-relay"

$acl = Get-Acl "C:\Program Files\UiPathRelay"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($account, "ReadAndExecute", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\Program Files\UiPathRelay" $acl

$acl = Get-Acl "C:\ProgramData\UiPathRelay"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($account, "Modify", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\ProgramData\UiPathRelay" $acl

These commands add the service account to the permissions already on each path. They do not remove permissions other accounts may have. If the dependencies directory is outside C:\Program Files, also grant the account Read & Execute there and remove write access for non-administrators.

Starting with a custom service account

.\relay.exe start --config-file C:\path\to\config.txt `
  --accept-license-agreement `
  --service-account "DOMAIN\svc-relay" `
  --service-account-password "<password>"

--service-account-password is required for domain or local user accounts. PowerShell records the command line in its history file, and the password is visible in the process command line while the command runs, so prefer a Group Managed Service Account (gMSA), which requires no password.

When the on-prem executor is enabled, run the service under a dedicated account rather than LocalSystem. The executor loads third-party connector libraries with the service account's privileges, and LocalSystem is the highest-privilege local account.

For that account:

• Grant only the permissions in NTFS permissions, plus the right to log on as a service.
• Do not add it to the Administrators group.
• Re-apply those permissions, including the dependencies directory and the Java installation, if you change the account later.

Group Managed Service Accounts (gMSA)

# Install the gMSA on the server (run once per server)
Install-ADServiceAccount -Identity "gMSA-Relay$"

# Start the Relay client with gMSA (no password required)
.\relay.exe start --config-file config.txt --service-account "DOMAIN\gMSA-Relay$" --accept-license-agreement

gMSAs rotate passwords automatically and eliminate credential management overhead.

Windows Service details

Viewing service status

Via Services console

1. Open Run (Win + R) and type services.msc.
2. Locate the service with display name Relay - <id>.
3. Open the context menu to start, stop, restart, or view properties.

Via PowerShell

# All Relay services
Get-Service "Relay-*"

# Detailed information
Get-Service "Relay-<id>" | Format-List *

# Service configuration (account, start mode)
Get-CimInstance Win32_Service -Filter "Name LIKE 'Relay-%'" | Select-Object Name, StartMode, State, StartName

Service recovery

When the Relay client installs itself as a service, it configures automatic recovery:

• First failure: restart after 10 seconds
• Second failure: restart after 30 seconds
• Subsequent failures: restart with escalating delays

To review or adjust recovery settings: open services.msc > right-click the service > Properties > Recovery tab.

Event Viewer

Use Event Viewer (eventvwr.msc) to diagnose service issues.

Log	Path	Events
System	Windows Logs > System	Service start, stop, crash, and recovery (7000-series)
Application	Windows Logs > Application	Application errors

Query relay events via PowerShell

Get-WinEvent -FilterHashtable @{LogName='System'; ID=7000,7009,7031,7034,7036,7045} -MaxEvents 100 |
  Where-Object { $_.Message -like '*Relay*' } |
  Format-Table TimeCreated, Id, Message -Wrap

Event ID	Meaning
7000	Service failed to start. Check account permissions
7009	Timeout waiting for service. Check network connectivity
7031	Service crashed and recovery action taken. Check relay.log
7034	Service terminated unexpectedly. Check for resource exhaustion
7045	New service installed (confirms successful installation)

Proxy configuration

Windows services inherit environment variables from the system (HKLM). Set proxy variables at the Machine level before starting the Relay client:

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://proxy.corp.example.com:8080", "Machine")
[Environment]::SetEnvironmentVariable("NO_PROXY", "localhost,127.0.0.1,.corp.example.com", "Machine")
.\relay.exe start --config "<your-config>" --accept-license-agreement

Setting proxy variables at the user level is not sufficient. System services ignore user-level environment variables.

To update the proxy: change the system-level variable and run .\relay.exe restart <id>.

To remove the proxy: [Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "Machine"), then .\relay.exe restart <id>.

To verify: [Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine").

For supported proxy schemes and authentication, see the proxy section in Deploying the Relay client.

Windows Firewall

If outbound traffic is restricted by Windows Firewall, add an outbound rule for the Relay client binary.

If the on-prem executor is enabled and outbound program rules are enforced, also allow the Java executable used by the executor to connect to the target host and port of each supported TCP-based connection. Scope the rule to those destinations rather than allowing all outbound traffic.

No inbound rule is required. The executor listens on the loopback interface only, on port 18080 by default, and accepts no connections from outside the host. Do not open that port. To confirm the listener is bound to loopback, run Get-NetTCPConnection -LocalPort 18080 -State Listen and check that LocalAddress is 127.0.0.1 or ::1.

Setting	Value
Direction	Outbound
Program	C:\Program Files\UiPathRelay\relay.exe
Protocol / Port	TCP / 443
Profiles	Domain, Private

Via PowerShell

New-NetFirewallRule -DisplayName "UiPath Relay - Outbound HTTPS" `
  -Direction Outbound `
  -Program "C:\Program Files\UiPathRelay\relay.exe" `
  -Protocol TCP `
  -RemotePort 443 `
  -Action Allow `
  -Profile Domain,Private

# Verify rule
Get-NetFirewallRule -DisplayName "UiPath Relay*" | Format-Table Name, Enabled, Direction, Action

Via GUI (Windows Defender Firewall with Advanced Security):

1. Open wf.msc.
2. Select Outbound Rules > New Rule.
3. Choose Program and specify: C:\Program Files\UiPathRelay\relay.exe.
4. Select Allow the connection.
5. Apply to Domain and Private profiles.
6. Name the rule: UiPath Relay - Outbound HTTPS.

If your organization manages firewall rules via Group Policy or a third-party firewall, work with your Windows administrator to add an equivalent rule.

Antivirus and endpoint protection

Add exclusions for the Relay client binary and its data directories to prevent interference.

Type	Path
Binary	C:\Program Files\UiPathRelay\relay.exe
Data and logs	C:\ProgramData\UiPathRelay\
Java executable (executor only)	The full path of the java.exe the executor uses
Connector libraries (executor only)	The dependencies directory

Do not add a process exclusion for java.exe. It stops endpoint protection from inspecting a process whose job is loading third-party code and reaching internal systems, and a bare file name applies to every Java process on the host. Use path exclusions, and give any process exclusion as a full path.

If you use application control such as Windows Defender Application Control (WDAC) or AppLocker, note that onprem-executor.jar is replaced on every Relay client upgrade, so a rule that allows a specific file hash stops matching after each upgrade. Use path or publisher rules, and re-approve the JAR as part of your upgrade procedure.

If you used custom paths via --bin-dir, --data-dir, or --logs-dir, exclude those paths instead.

Windows Defender via PowerShell

Add-MpPreference -ExclusionPath "C:\Program Files\UiPathRelay"
Add-MpPreference -ExclusionPath "C:\ProgramData\UiPathRelay"
Add-MpPreference -ExclusionProcess "relay.exe"

Windows Defender via GUI

1. Open Windows Security > Virus & threat protection > Manage settings.
2. Under Exclusions, select Add or remove exclusions.
3. Add folder exclusions: C:\Program Files\UiPathRelay\ and C:\ProgramData\UiPathRelay\.
4. Add process exclusion: relay.exe.

For centrally managed endpoint protection (CrowdStrike, Symantec, Microsoft Defender for Endpoint via Intune/SCCM), work with your security administrator to add the exclusions above.

Uninstall

1. Delete all Relay clients (use .\relay.exe list to see installed groups):

   .\relay.exe delete <id>
   

2. Remove the shared binary:

   Remove-Item "C:\Program Files\UiPathRelay" -Recurse
   

3. Remove remaining data directories:

   Remove-Item "C:\ProgramData\UiPathRelay" -Recurse
   

4. Remove Windows Defender exclusions:

   Remove-MpPreference -ExclusionPath "C:\Program Files\UiPathRelay"
   Remove-MpPreference -ExclusionPath "C:\ProgramData\UiPathRelay"
   Remove-MpPreference -ExclusionProcess "relay.exe"
   

5. Remove the Windows Firewall rule:

   Remove-NetFirewallRule -DisplayName "UiPath Relay - Outbound HTTPS"
   

For rules added via Group Policy or a third-party firewall, work with your Windows administrator to remove them.

Troubleshooting

Symptom	Cause	Resolution
Service fails to start	Insufficient permissions	Open PowerShell as Administrator
permission denied	Cannot write to Program Files or ProgramData	Verify Administrator access, or use --bin-dir / --data-dir for writable paths
does not have the 'Log on as a service' right	Custom account missing SeServiceLogonRight	Grant via Local Security Policy > User Rights Assignment, or use Group Policy
not a valid Windows account	Wrong format for --service-account	Use .\username for local accounts or DOMAIN\username for domain accounts
marked for deletion / service pending deletion	services.msc has an open handle	Close services.msc and retry; reboot if the issue persists
service is disabled	Disabled via services.msc or Group Policy	Re-enable: Set-Service -Name "Relay-<id>" -StartupType Automatic
file is locked by another process	Binary in use during update	Stop the Relay client service first, then retry
path exceeds Windows path length limit	Data/logs path exceeds 260 characters	Use shorter paths for --data-dir and --logs-dir
Antivirus blocking relay.exe	Endpoint protection quarantined binary	Add exclusions (see Antivirus and endpoint protection); check quarantine and restore
Service running but tunnel not established	Network or authentication issue	Check relay.log for login to server errors; verify connectivity to cloud.uipath.com; for Relay client versions earlier than 26.4.2, verify TLS passthrough to the regional relay hostname
DPAPI decrypt failed	Machine identity changed after VM clone or reimage	Re-provision the relay with a fresh configuration from UiPath Administration
Proxy not used by service	Proxy set at user level, not system level	Set HTTPS_PROXY at the Machine level (see Proxy configuration); restart the service

Diagnostic commands

# Real-time logs
.\relay.exe logs <id> -f

# Service details
Get-Service "Relay-<id>" | Format-List *

# Connectivity test
Test-NetConnection -ComputerName cloud.uipath.com -Port 443

# Required only for Relay client versions earlier than 26.4.2
Test-NetConnection -ComputerName <region>-relay.uipath.com -Port 443

For authentication and connectivity errors shared across platforms, see Troubleshooting.

Quick reference

Action	Command
Start	.\relay.exe start --config-file config.txt --accept-license-agreement
Stop	.\relay.exe stop <id>
Restart / upgrade	.\relay.exe restart <id>
Delete	.\relay.exe delete <id>
Delete (force)	.\relay.exe delete <id> --force
List	.\relay.exe list
Describe	.\relay.exe describe <id>
Logs	.\relay.exe logs <id> -f
Service status	Get-Service "Relay-<id>"
Services console	services.msc