Deploying the Relay client on Windows

This page covers production setup details specific to Windows. For cross-platform prerequisites, and networking 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 服务器	2019 年
Windows Desktop	10 Enterprise

其他要求：

• 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.

Pre-installation checklist

系统

• Windows Server 2019+ or Windows 10 Enterprise+
• PowerShell 5.1 or later
• Administrator access to the target machine
• Minimum 200 MB free disk space

网络

• Outbound HTTPS (port 443) to cloud.uipath.com is allowed
• Outbound TLS (port 443) to <region>-relay.uipath.com is allowed
• TLS passthrough configured for the relay endpoint (no TLS inspection)
• Relay node has network access to all on-premises services you plan to expose

安全性

• Service account created (if not using LocalSystem) — see Service account and permissions
• Windows Defender and antivirus exclusions planned — see Antivirus and endpoint protection

配置

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

Validation commands (run 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

安装

1. Download and extract

架构	存档
x86_64	relay-windows-amd64.zip
ARM64	relay-windows-arm64.zip

Extract the zip archive. It contains a single relay.exe binary, ready to run.

2. Start

Open PowerShell as Administrator before running any start command.

You can provide the client configuration string (from UiPath Administration — see 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>"

Option B — File. Save the configuration to a file, then reference it. Recommended — keeps the secret out of shell history:

Set-Content -Path "config.txt" -Value "<your-config>"
.\relay.exe start --config-file C:\path\to\config.txt

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.

预期输出：

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>")

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 `
  --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

管理

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

列表

Shows all installed relay groups on this machine with status and version. Does not require Administrator privileges.

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

停止

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>

Binary upgrade: download the new relay.exe and run .\relay.exe restart <id> from it. The restart command compares the running binary against the installed copy by SHA256 hash and updates the installed binary automatically if they differ.

场景	命令
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
Binary upgrade	Download new binary, then .\relay.exe restart <id>

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

删除

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

版本

.\relay.exe version

There is no auto-upgrade. To update, download the new binary and run .\relay.exe restart <id> 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
  logs\<id>\
    relay.log                                # Current log
    relay.YYYYMMDD-HHMMSS.log                # Rotated logs

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 at install time:

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

标记	默认	描述
--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

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>\

--bin-dir, --data-dir, and --logs-dir are only accepted by the start command. Other commands (stop, restart, 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

右侧	描述	如何配置
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

路径	所需权限
C:\Program Files\UiPathRelay\	Read & Execute
C:\ProgramData\UiPathRelay\	Read, Write, Modify
C:\ProgramData\UiPathRelay\logs\	Read, Write, Modify, Delete

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

Starting with a custom service account

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

--service-account-password is required for domain or local user accounts. Managed Service Accounts (gMSA) do not require a password.

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$"

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. Right-click 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.

日志	路径	Events
系统	Windows Logs > System	Service start, stop, crash, and recovery (7000-series)
应用程序	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

活动 ID	意义
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

代理配置

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>"

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.

设置	值
方向	Outbound
程序	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.

类型	路径
二进制	C:\Program Files\UiPathRelay\relay.exe
Data and logs	C:\ProgramData\UiPathRelay\

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.

卸载

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.

故障排除

症状	原因	分辨率
Service fails to start	权限不足	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 TLS passthrough
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 <region>-relay.uipath.com -Port 443

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

快速参考

操作	命令
启动	.\relay.exe start --config-file config.txt
停止	.\relay.exe stop <id>
Restart / upgrade	.\relay.exe restart <id>
删除	.\relay.exe delete <id>
Delete (force)	.\relay.exe delete <id> --force
列表	.\relay.exe list
日志	.\relay.exe logs <id> -f
Service status	Get-Service "Relay-<id>"
Services console	services.msc