- Getting started
- Data security and compliance
- Organizations
- Authentication and security
- Licensing
- About licensing
- Unified Pricing: Licensing plan framework
- Activating your Enterprise license
- Migrate from Test Suite to Test Cloud
- License migration
- Assigning licenses to tenants
- Assigning user licenses
- Deallocating user licenses
- Monitoring license allocation
- License overallocation
- Licensing notifications
- User license management
- Tenants and services
- Accounts and roles
- AI Trust Layer
- External applications
- Notifications
- Logging
- Data Export
- Testing in your organization
- Troubleshooting
- Migrating to Test Cloud
Test Cloud admin guide
Install and start the Relay client on a machine inside your network to establish the outbound tunnel to Test Cloud. Before you begin, configure a Relay Group and have the client configuration string ready.
Prerequisites
Hardware requirements
| Profile | vCPU | RAM | Relay Groups | Endpoints per group | Use case |
|---|---|---|---|---|---|
| Standard | 1 | 2 GB | Up to 10 | Up to 50 | Most deployments |
| Large | 2 | 4 GB | 10+ | Up to 50 | High-throughput or large-scale environments |
These are minimum requirements for the Relay client process. If the machine runs other workloads, provision additional resources accordingly.
Disk requirements
| Profile | Minimum free disk |
|---|---|
| Standard (1–10 groups) | 200 MB |
| Large (10+ groups) | 1 GB |
Supported operating systems
| Architecture | Linux | Windows |
|---|---|---|
| x86_64 (amd64) | Supported | Supported |
| ARM64 (aarch64) | Supported | Supported |
Network requirements
The Relay client requires outbound-only connectivity. No inbound firewall rules are needed.
Starting with Relay client 26.4.2, new Relay client configurations can connect the persistent tunnel through the standard Automation Cloud URL, cloud.uipath.com. These configurations do not require a region-specific relay hostname allowlist for the tunnel.
| Relay client configuration | Protocol | Port | Destination | TLS passthrough required | Purpose |
|---|---|---|---|---|---|
Relay client 26.4.2 or later | HTTPS / WSS | 443 | cloud.uipath.com | Not required | Authentication, relay registration, and persistent tunnel |
Relay client versions earlier than 26.4.2 | TLS | 443 | <region>-relay.uipath.com | Required | Persistent tunnel |
Relay client versions earlier than 26.4.2 continue to work with regional relay hostnames. Keep those hostnames allowlisted until you move to Relay client 26.4.2 or later and connect through cloud.uipath.com.
For Relay client versions earlier than 26.4.2, replace <region> with the region of your Test Cloud tenant.
| Region | Relay server hostname |
|---|---|
| US | us-relay.uipath.com |
| EU | eu-relay.uipath.com |
| Canada | ca-relay.uipath.com |
| Switzerland | ch-relay.uipath.com |
| Australia | au-relay.uipath.com |
| Singapore | sg-relay.uipath.com |
| Japan | jp-relay.uipath.com |
| South Korea | kr-relay.uipath.com |
| UAE | ae-relay.uipath.com |
| UK | uk-relay.uipath.com |
| GXP EU | gxp-eu-relay.uipath.com |
| GXP US | gxp-us-relay.uipath.com |
Contact UiPath support to confirm the relay server hostname if your tenant region is not listed above.
Choose the region that matches your UiPath Cloud tenant region, not the physical location of the relay node. For example, if your tenant is provisioned in the US region, use us-relay.uipath.com even if the relay itself runs in a different geography. Relay client 26.4.2 configurations that connect through cloud.uipath.com do not use this regional hostname.
Latency considerations: Because traffic traverses UiPath Cloud → relay server → relay node → on-premises service, placing the relay node geographically close to your tenant's region minimizes round-trip time and improves overall throughput.
For Relay client 26.4.2 configurations that connect through cloud.uipath.com, configure firewalls and proxies to allow HTTPS traffic and WebSocket upgrades to cloud.uipath.com:443. If a proxy inspects TLS for cloud.uipath.com, install the proxy's signing CA in the OS trust store used by the Relay client, and make sure the proxy allows WebSocket upgrades. For Relay client versions earlier than 26.4.2, configure your firewall and any TLS-inspecting proxy or DLP appliance to allow TLS passthrough for <region>-relay.uipath.com:443; TLS inspection on the regional relay hostname breaks the relay tunnel.
The machine running the Relay client must also have direct network access to all on-premises services you plan to expose. Plan the placement of the Relay client accordingly.
The relay node must be able to resolve the hostname and open a connection to the registered port for every endpoint in its relay group at runtime. The routing path is flexible — a direct network route, corporate egress proxy, or jump host are all acceptable — as long as the connection succeeds from the relay node. Plan placement so that every endpoint in the group remains reachable.
Bandwidth
The control channel (heartbeats and authentication) uses approximately 1–2 KB/minute when idle. Data traffic scales with the volume of requests your cloud services send to on-premises endpoints — the relay acts as a transparent tunnel with no additional overhead beyond TLS and lightweight WebSocket framing for cloud.uipath.com connections.
Verify connectivity
Before installing the Relay client, confirm that outbound traffic on port 443 is allowed to the required destinations for your configuration.
Linux
nc -zv cloud.uipath.com 443
# Required only for Relay client versions earlier than 26.4.2
nc -zv <region>-relay.uipath.com 443
nc -zv cloud.uipath.com 443
# Required only for Relay client versions earlier than 26.4.2
nc -zv <region>-relay.uipath.com 443
Windows (PowerShell)
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
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
A successful result shows TcpTestSucceeded : True on Windows and succeeded on Linux. If a required check fails, review your firewall rules. For Relay client 26.4.2 configurations that connect through cloud.uipath.com, confirm that WebSocket upgrades are allowed; for Relay client versions earlier than 26.4.2, confirm that TLS passthrough is configured for the relay server hostname.
Configure a proxy (if applicable)
If your network routes outbound traffic through a proxy, set the following environment variables before running relay start. The Relay client applies the proxy to all outbound connections.
| Variable | Purpose |
|---|---|
HTTPS_PROXY / https_proxy | Proxy URL (checked first) |
HTTP_PROXY / http_proxy | Proxy URL (fallback) |
NO_PROXY / no_proxy | Comma-separated hosts or domains that bypass the proxy |
The proxy URL must use one of these schemes: http://, https://, socks5://, or ntlm://. Format: scheme://[user:password@]host:port.
For https:// proxies: the Relay client validates the proxy's TLS certificate against the OS trust store. If your proxy uses a corporate or self-signed CA, add that CA to the Relay client machine's trust store before starting the relay; otherwise, the TLS handshake fails with a certificate verification error.
For Relay client 26.4.2 configurations that connect through cloud.uipath.com, configure your proxy to allow long-lived HTTPS connections and WebSocket upgrades to cloud.uipath.com:443. If the proxy inspects TLS for cloud.uipath.com, install the proxy's signing CA in the OS trust store used by the Relay client. For Relay client versions earlier than 26.4.2, configure your proxy to bypass TLS inspection for <region>-relay.uipath.com:443. PAC files, WPAD auto-discovery, and proxy chaining are not supported — set the proxy URL explicitly. When a proxy is detected, the prerequisite checks show via proxy in the output.
Security: The Relay client redacts proxy passwords in logs. However, credentials set in environment variables may be visible in process listings and systemd unit files. Use dedicated service credentials and restrict access to the relay node accordingly.
Configure trusted IPs (if applicable)
If your organization restricts access by IP address, add the NAT IP of the machine running the Relay client to the trusted IP list in UiPath Administration. The Relay client's outbound traffic reaches Test Cloud from this IP address, so it must be explicitly allowed.
For instructions, see Adding trusted IP ranges.
Accept the license agreement
Before starting the Relay client, you must accept the license agreement. Choose one of the following methods:
Option 1 (Environment variable) — Set the LICENSE_AGREEMENT environment variable to accept:
Linux
export LICENSE_AGREEMENT=accept
export LICENSE_AGREEMENT=accept
Windows
$env:LICENSE_AGREEMENT=accept
$env:LICENSE_AGREEMENT=accept
Option 2 (Inline parameter) — Append --accept-license-agreement to the relay start command:
./relay start --config "<your-config>" --accept-license-agreement
./relay start --config "<your-config>" --accept-license-agreement
Setup guides
For production deployments, refer to the platform guide for your operating system — it covers directory structure, service management, security framework configuration, and uninstall procedures:
| Platform | Guide |
|---|---|
| Linux | Deploying the Relay client on Linux |
| Windows | Deploying the Relay client on Windows |
| Container | Deploying the Relay client as a container |
Operations
Connection resilience
The Relay client maintains the tunnel automatically:
- Heartbeats every 30 seconds by default (configurable via
--heartbeat-interval, minimum 10 seconds). The tunnel timeout is 3× the heartbeat interval. Lower the interval if your firewall, proxy, or NAT drops idle TCP connections before 30 seconds:relay start --config "<config>" --heartbeat-interval 10 relay restart <id> --heartbeat-interval 10relay start --config "<config>" --heartbeat-interval 10 relay restart <id> --heartbeat-interval 10 - Auto-reconnect on disconnect, using exponential backoff scaling to 20-second intervals.
- Service auto-restart if the process crashes, managed by systemd on Linux and Windows Service Control Manager on Windows.
- Service auto-start on system reboot.
Proactive reconnect
Some networks — behind a corporate proxy, load balancer, or firewall with an idle-connection timeout — silently terminate long-lived TLS connections. Proactive reconnect re-establishes the control connection on a fixed schedule to prevent this.
Enable it with the --reconnect-interval flag:
relay start --config "<config>" --reconnect-interval 1800
relay start --config "<config>" --reconnect-interval 1800
The effective minimum is 1800 seconds (30 minutes). Set the interval to roughly half the idle timeout of your network appliance — for example, 1800 seconds for a 60-minute firewall timeout. Leave disabled on stable networks without an idle-connection timeout.
Graceful draining. When the interval elapses, the Relay client stops accepting new work and waits for in-flight connections to complete — up to a 300-second drain timeout — before closing the old connection and opening a new one. Requests still in flight when the drain timeout is reached are terminated.
High availability. When multiple Relay clients are deployed in the same group, they coordinate so that only one client drains at a time. The group continues serving traffic throughout each reconnect cycle.
Signs that proactive reconnect is needed: Logs show periodic unexpected EOF errors or silent disconnects despite a stable underlying network — typically caused by a 30–60 minute idle timeout on a firewall, proxy, or load balancer.
Reload configuration
relay reload <id>
relay reload <id>
Re-fetches proxy configuration from Test Cloud and applies it without restarting. Cloud-side changes — new endpoints, updated health-check paths — are pushed automatically to a running Relay client and do not normally require a reload. Use this command as a fallback only if a newly added endpoint returns 404.
Logging
| Setting | Value |
|---|---|
| Default level | info |
| Rotation | Daily |
| Retention | 7 days |
| Log file | relay.log (current), relay.YYYYMMDD-HHMMSS.log (rotated) |
Override the default log level with --log-level trace/debug/info/warn/error. In Relay client 26.4.2 or later, override rotated log retention with --log-retention-days <days> on relay start or relay restart; the minimum retention is 7 days.
Command reference
relay start
Provision a new Relay client and start it as a background service.
Configuration (one required)
-c,--config <string>— inline base64-encoded configuration string.--config-file <path>— path to a file containing the configuration string. Recommended — keeps the secret out of shell history.
Tuning (optional)
--heartbeat-interval <sec>— tunnel heartbeat interval. Default30. Minimum10. Tunnel timeout is 3× this value. Lower if your firewall, NAT, or proxy drops idle TCP before 30 seconds.--reconnect-interval <sec>— proactive reconnect interval. Default0(disabled); effective minimum1800(30 minutes) when set.--log-level <level>—trace,debug,info,warn, orerror. Defaultinfo.--log-retention-days <days>— number of days to retain rotated log files. Default7. Minimum7. Requires Relay client26.4.2or later.-d,--detach=false— run in the foreground instead of as a background service. Useful for debugging startup issues.
Non-default install paths (optional)
--data-dir <path>— configuration directory.--logs-dir <path>— log file directory.--bin-dir <path>— binary install directory.
Linux only
--user-mode— install as a systemd user service (nosudorequired, uses XDG paths).
Windows only
--service-account <DOMAIN\user>— run the Windows service under a specific account. Default isLocalSystem.--service-account-password <password>— password for--service-account.
relay restart
Stop and restart the Relay client service. Detects updated binaries and applies service definition changes. The following flags can be overridden at restart time (all default to unchanged unless noted):
--config/--config-file— replace the client configuration.--accept-license-agreement— accept the license agreement during restart, useful when upgrading an older installed service that did not persist license acceptance.--log-level— change the log level.--logs-dir <path>— relocate the installed service's log directory. Requires Relay client26.4.2or later.--log-retention-days <days>— change rotated log retention. Minimum7; pass-1to leave unchanged. Requires Relay client26.4.2or later.--heartbeat-interval— change the heartbeat interval. Minimum10; pass0to leave unchanged.--reconnect-interval— change the proactive reconnect interval. Minimum1800(30 minutes) when set. Pass0to disable, or-1to leave unchanged.
relay logs
Show log output for a Relay client.
-f,--follow— stream new log lines continuously.-n,--lines <N>— number of lines from the end. Default50.
relay list
Show all Relay clients on this machine with status, version, creation and update timestamps, and group name when available. Long group names are truncated in table output.
--json— emit JSON output for automation and scripting, including full group names.
relay describe (Relay client 26.4.2 or later)
26.4.2 or later)Show detailed information for one Relay client, including group ID and name, secret ID, status, version, service mode and executable path, configured heartbeat and reconnect intervals, log level, local paths, and timestamps.
--json— emit JSON output for automation and scripting.
relay reload
Re-fetch proxy configuration from Test Cloud and apply it without restarting. Use as a fallback if a newly added endpoint returns 404.
relay stop
Stop the Relay client service. Configuration and credentials are preserved — the Relay client can be restarted later.
relay delete
Stop the service, deregister from Test Cloud, and remove all local configuration and credentials.
-f,--force— remove locally without cloud deregistration. Use when credentials are unreadable or cloud-side resources have already been deleted.
relay support-bundle [id]
Collect a redacted archive of configuration, logs, and system metadata for a UiPath support ticket. Omit [id] to bundle all Relay clients on the machine. Credentials and encryption keys are never included. See Relay troubleshooting for full details.
relay version
Print the Relay client version, build date, and git commit hash.
Antivirus and endpoint security
If your organization runs endpoint protection software, add exclusions for the relay binary and its data directory to prevent the Relay client from being blocked or quarantined. For Relay client 26.4.2 configurations that connect through cloud.uipath.com, allow cloud.uipath.com:443. For Relay client versions earlier than 26.4.2, configure TLS-inspecting proxies, DLP appliances, and IDS/IPS systems to bypass inspection for <region>-relay.uipath.com:443.
| Destination | Port | Protocol | Action |
|---|---|---|---|
cloud.uipath.com | 443 | HTTPS | Allow |
<region>-relay.uipath.com | 443 | TLS | Allow + bypass TLS inspection for Relay client versions earlier than 26.4.2 |
- Prerequisites
- Hardware requirements
- Disk requirements
- Supported operating systems
- Network requirements
- Bandwidth
- Verify connectivity
- Configure a proxy (if applicable)
- Configure trusted IPs (if applicable)
- Accept the license agreement
- Linux
- Windows
- Setup guides
- Operations
- Connection resilience
- Proactive reconnect
- Reload configuration
- Logging
- Command reference
- relay start
- relay restart
- relay logs
- relay list
- relay describe
(Relay client 26.4.2or later) - relay reload
- relay stop
- relay delete
- relay support-bundle [id]
- relay version
- Antivirus and endpoint security