Deploying the Relay client

Relay client prerequisites, minimum requirements, and cross-platform setup steps for connecting your on-premises network to Test Cloud.

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 GiB	Up to 10	Up to 50	Most deployments
Large	2	4 GiB	10+	Up to 50	High-throughput or large-scale environments

These are minimum requirements for the Relay client when the on-prem executor is not enabled. If the host also runs other workloads, add capacity for them on top of these figures. For deployments that enable the executor, use the figures in Resource planning for supported TCP-based connections instead.

Resource planning for supported TCP-based connections

Each Relay Group you install runs as its own Relay client service. With the on-prem executor enabled, that service starts and supervises one Java process. The figures below are for a single Relay Group with the executor enabled.

Profile	vCPU	RAM	RAM reserved for executor
Standard (with executor)	2	4 GiB	1 GiB
Large (with executor)	4 or more	4 GiB or more	1 GiB or more

RAM includes the executor reservation, the operating system, and the Java runtime. Add capacity for monitoring and any other workloads on the host. After go-live, if the executor's memory use approaches its reservation, raise the reservation and the RAM together.

Tip:

To minimize resource usage, register all your TCP-based endpoints under a single Relay Group. Its Relay client then runs one on-prem executor for every TCP-based endpoint, so you reserve memory, size the host, and monitor executor logs for a single process.

If your network segmentation or availability requirements call for more than one Relay Group with the executor on the same host:

• Assign each group's executor a unique --onprem-executor-listen-port value.
• Reserve another 1 GiB for each additional executor process.
• Size CPU for the total traffic across all groups, rather than multiplying the per-group CPU figure by the number of groups.
• Allow disk for a separate executor JAR and log file per group.

Disk requirements

Profile	Minimum free disk
Standard (1–10 groups)	200 MB
Large (10+ groups)	1 GB

The minimums above cover the Relay client alone. If you enable the on-prem executor, allow additional space for the Java runtime, onprem-executor.jar, the connector libraries you supply, and retained executor logs. Log growth depends on your traffic volume, log level, and the configured retention period.

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.

Every Relay client version reaches cloud.uipath.com to authenticate and register. Starting with Relay client 26.4.2, new configurations also carry the persistent tunnel over that same URL, so they no longer need a region-specific relay hostname allowlisted.

Relay client configuration	Protocol	Port	Destination	TLS passthrough required	Purpose
All Relay client versions	HTTPS	443	cloud.uipath.com	Not required	Authentication and relay registration
Relay client 26.4.2 or later	HTTPS / WSS	443	cloud.uipath.com	Not required	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. For the full list of regions, see Global cloud regions.

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
European Union (delayed region)	gxp-eu-relay.uipath.com
United States (delayed region)	gxp-us-relay.uipath.com

Note:

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 travels from UiPath Cloud through the relay server and the relay node to the 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 Relay host must resolve and connect to every registered HTTP or HTTPS endpoint, and to the host and port of each supported TCP-based endpoint.

The routing path is flexible. A direct network route, a corporate egress proxy, or a jump host are all acceptable, as long as the connection succeeds from the Relay host. Plan placement so that every destination in the group stays 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. For HTTP and HTTPS endpoints, the relay acts as a transparent tunnel, with no additional overhead beyond TLS and the lightweight WebSocket framing used for cloud.uipath.com connections.

For supported TCP-based connections, the on-prem executor translates each request into the connector's protocol. Traffic between the executor and the target system therefore reflects that protocol rather than the size of the original request. Traffic between the Relay client and the executor stays on the loopback interface and does not leave the host.

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

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

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.

On-prem executor for supported TCP-based connections

For supported TCP-based connections, such as SAP BAPI, requests are handled by the on-prem executor, a Java process that speaks the connector's protocol and forwards the call to the target system. In Linux and Windows service deployments, described below, the Relay client starts and supervises it. In container deployments you run it as a separate container: see SAP BAPI and other TCP-based connections.

Important:

On-prem executor support requires Relay client 26.4.3 or later.

The Relay client starts one executor process for each Relay client service, in Linux and Windows service deployments. The executor listens on localhost only, on port 18080 by default, and is not reachable from outside the host. Like any loopback service it is reachable by other processes on the same host, so treat local access to the Relay host as sensitive.

Before you enable it:

• Have a Java 21 or later runtime available. A JRE or JDK is sufficient, and an existing installation works. Either put java on the PATH of the account that runs relay start, or pass the runtime's location with --onprem-executor-java-home.
• Extract the Relay binary, relay on Linux or relay.exe on Windows, and the bundled onprem-executor.jar from the same archive. Leave the two files together in the extracted directory, and run installation or upgrade commands from that directory.
• Make sure the Relay host can reach the target system hostname and port.
• If a connector requires libraries that UiPath does not ship, put them all in one durable directory that the Relay service account can read, then point --onprem-executor-dep-dir at it. The Relay client stores the path but does not copy the files.
• For SAP BAPI, that directory holds the SAP JCo 3 files sapjco3.jar and sapidoc3.jar, plus the native library matching the host operating system and Java runtime architecture. Use the SAP JCo release that SAP supports for your SAP system and Java runtime.
• The dependencies directory is a code-load path for the executor, which runs with the Relay service account's privileges. It must be administrator-owned and must not be writable by unprivileged users.
• On Linux, use 0755 for the directory and 0644 for the files. On Windows, place it under C:\Program Files, which grants administrators write access and other accounts read and execute by default.

For copyable installation and verification commands, see Linux or Windows. After installing, relay describe <id> reports whether the executor is enabled and which Java home and dependencies directory it uses.

Important:

In a container deployment, the Relay client does not start the executor, so the Java runtime and dependencies directory requirements for service deployments do not apply, and --onprem-executor-java-home and --onprem-executor-dep-dir have no effect. Run the executor as a separate container instead, as described in SAP BAPI and other TCP-based connections.

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 uses these settings for proxy-aware outbound traffic.

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.

Important:

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

Windows

$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

Setup guides

For production deployments, refer to the platform guide for your operating system. It covers quick start commands, 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 --accept-license-agreement
  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

Networks behind a corporate proxy, load balancer, or firewall with an idle-connection timeout can 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 --accept-license-agreement

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>

Re-fetches proxy configuration from Test Cloud and applies it without restarting. Cloud-side changes, such as new endpoints or 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.

License agreement (one required)

• --accept-license-agreement: accept the end-user license agreement inline.
• LICENSE_AGREEMENT=accept: environment-variable equivalent to the flag. relay start prints the EULA and exits if neither is set.

Configuration (one required)

• -c, --config <string>: inline base64-encoded configuration string.
• --config-file <path>: path to a file containing the configuration string. Recommended: it keeps the secret out of shell history.

Tuning (optional)

• --heartbeat-interval <sec>: tunnel heartbeat interval. Default 30. Minimum 10. 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. Default 0 (disabled); effective minimum 1800 (30 minutes) when set.
• --log-level <level>: trace, debug, info, warn, or error. Default info.
• --log-retention-days <days>: number of days to retain rotated log files. Default 7. Minimum 7. Requires Relay client 26.4.2 or later.
• -d, --detach=false: run in the foreground instead of as a background service. Useful for debugging startup issues.

On-prem executor (optional)

• --enable-onprem-executor: enable the on-prem executor. In Linux and Windows service deployments, the Relay client starts the bundled executor process. In a container deployment, it connects to the executor container on the default port 18080.
• --onprem-executor-listen-port <port>: port the on-prem executor listens on. Default 18080. In a container deployment, use the executor container's SERVER_PORT value. This flag alone also enables the executor.
• --onprem-executor-java-home <path>: JAVA_HOME used to run the on-prem executor. If omitted, java is resolved from PATH. No effect in a container deployment.
• --onprem-executor-dep-dir <path>: single directory holding every connector dependency, both the JARs and the matching native OS libraries. For SAP BAPI, that is sapjco3.jar, sapidoc3.jar, and the SAP JCo native library for the host. No effect in a container deployment, where the executor image owns this path.

The executor address is fixed to localhost. Relay log level and retention settings also apply to onprem-executor.log.

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 (no sudo required, uses XDG paths).

Windows only

• --service-account <DOMAIN\user>: run the Windows service under a specific account. Default is LocalSystem.
• --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 client 26.4.2 or later.
• --log-retention-days <days>: change rotated log retention. Minimum 7; pass -1 to leave unchanged. Requires Relay client 26.4.2 or later.
• --heartbeat-interval: change the heartbeat interval. Minimum 10; pass 0 to leave unchanged.
• --reconnect-interval: change the proactive reconnect interval. Minimum 1800 (30 minutes) when set. Pass 0 to disable, or -1 to leave unchanged.
• --enable-onprem-executor: enable or update the on-prem executor settings on an installed service.
• --disable-onprem-executor: remove persisted on-prem executor settings and restart without the executor process.
• --onprem-executor-listen-port, --onprem-executor-java-home, --onprem-executor-dep-dir: update specific on-prem executor settings. Passing any of these flags implies an executor update.

If the installed service already has the on-prem executor enabled, relay restart <id> preserves its settings. To upgrade Relay and the executor together, extract both files from the new archive and run relay restart <id> using the new Relay binary. Java and executor checks run before the service is stopped.

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. Default 50.

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)

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.

An On-Prem Executor section reports whether the executor is enabled and, when it is, the listen port, runtime version, runtime path, Java home, and dependencies directory.

• --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 Collect a support bundle 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.

If you enable the on-prem executor, extend those exclusions to the Java executable, the dependencies directory, and onprem-executor.log. The Relay service starts a Java child process that loads third-party connector libraries, which some endpoint protection products block by default. Scope the exclusions to those paths rather than the whole directory tree.

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