Deploying the Relay client on Linux

Deploy the Relay client as a systemd service on Linux to establish an outbound tunnel between your network and Test Cloud.

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

Operating system requirements

The Relay client requires systemd 229 or later. To verify: systemctl --version.

Distribution	Minimum version
Ubuntu	20.04 LTS (Focal)
Debian	10 (Buster)
Red Hat Enterprise Linux	8
Amazon Linux	2023
SUSE Linux Enterprise Server	15
Oracle Linux	8

Any Linux distribution with systemd 229+ is expected to work. For environments without systemd, the Relay client can run in foreground mode (--detach=false), but you are responsible for process management, auto-start, and recovery.

Required privileges: sudo (root) access is needed to install systemd services (/etc/systemd/system/), create default data and log directories, and copy the binary to /usr/local/bin/. For rootless installations, see User mode.

Prerequisites

System

• Supported Linux distribution with systemd 229+
• sudo (root) access, or plan to use --user-mode
• 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

• SELinux / AppArmor / fapolicyd exclusions configured (if applicable) (see Security frameworks)
• If you use the on-prem executor: an administrator-owned dependencies directory and Java installation that no unprivileged account can write. The executor loads code from both, with the privileges of the Relay service account

Configuration

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

Validate prerequisites

Run the following commands:

# Check systemd version (must be 229+)
systemctl --version

# Verify sudo access
sudo -v

# Check available disk space
df -h /var/lib

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

unzip relay_linux_amd64.zip && chmod +x relay

Starting with Relay client 26.4.3, the archive also contains onprem-executor.jar. Leave it next to the relay binary in the extracted directory, and run installation or upgrade commands from that directory.

2. Start

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:

sudo ./relay 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:

sudo ./relay start --config-file /path/to/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.

Important:

The on-prem executor loads and executes these libraries with the permissions of the Relay service account. Keep the directory, its parents, and every file in it owned and writable only by root, with read access for the service account. Anyone who can modify its contents can run code with those permissions.

For installations without root access, see On-prem executor in user mode.

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
libsapjco3.so	SAP JCo Linux 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, using an absolute path, so the executor uses the runtime you intend:

sudo ./relay start --config-file /path/to/config.txt \
  --accept-license-agreement \
  --enable-onprem-executor \
  --onprem-executor-java-home /usr/lib/jvm/java-21-openjdk \
  --onprem-executor-dep-dir /opt/uipath/relay/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, encrypts credentials, and installs a systemd 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: systemctl status relay-<id>

Note:

During startup, the Relay client automatically copies the binary to /usr/local/bin/relay. All relay groups on the machine share this single binary. Override the install directory with --bin-dir.

3. Verify

relay list

A healthy client shows ● running in the STATUS column. The ID value shown is used in all subsequent commands (relay stop <id>, relay 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:

sudo relay logs <id> -f

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

sudo relay 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:

sudo grep "Started OnPremRuntimeApplication" /var/log/uipath-relay/logs/<id>/onprem-executor.log
sudo tail -n 20 /var/log/uipath-relay/logs/<id>/onprem-executor.log

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

List

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

relay list
relay list --json

Describe

Note:

Available with Relay client 26.4.2 and later. Run relay 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 sudo. For a system service with the on-prem executor enabled, run it with sudo to include the executor version, which is read from the root-owned onprem-executor.jar.

relay describe <id>
relay describe <id> --json

Stop

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

sudo relay stop <id>

Restart and upgrade

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

sudo relay restart <id>

Upgrade: extract the new Relay client archive. Keep the new relay binary and matching onprem-executor.jar together, then run sudo ./relay 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 sudo ./relay 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	sudo relay restart <id>
Client secret rotation (inline)	sudo relay restart --config "<new-config>"
Client secret rotation (file)	sudo relay restart --config-file /path/to/new-config.txt
Log level change	sudo relay restart <id> --log-level debug
Log directory or retention change	sudo relay restart <id> --logs-dir /opt/mycompany --log-retention-days 30
Enable the on-prem executor	sudo ./relay restart <id> --enable-onprem-executor
Disable the on-prem executor	sudo relay restart <id> --disable-onprem-executor
Relay client upgrade	Extract the new archive, then run sudo ./relay 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.

sudo relay 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:

sudo relay delete <id> --force

Version

relay version

Note:

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

Directory structure

All directories are created automatically on first run.

/usr/local/bin/
  relay                                      # Shared binary (755)

/var/lib/uipath-relay/                       # Data root (755)
  groups/<id>/
    client_config                            # OAuth credentials (encrypted, 600)
    metadata.json                            # State, PID, install timestamps (644)
    .credentials.key                         # AES-256-GCM encryption key (600)
    onprem-executor.jar                      # Executor runtime when enabled (600)

/var/log/uipath-relay/                       # Logs root (755)
  logs/<id>/
    relay.log                                # Current log (644)
    relay.YYYYMMDD-HHMMSS.log                # Rotated logs (644)
    onprem-executor.log                      # Executor log when enabled

/etc/systemd/system/
  relay-<id>.service                         # Systemd unit file

File permissions

Path	Mode	Reason
Directories	755	Relay read/write access
client_config	600	Contains encrypted OAuth credentials
.credentials.key	600	AES-256-GCM encryption key
metadata.json	644	Service metadata (state, PID, install timestamps)
onprem-executor.jar	600	Executor runtime copied into protected service storage
relay.log	644	Readable for troubleshooting
Binary	755	Executable by systemd
Dependencies directory (executor only)	755, owned by root	You create it; the executor loads JARs and native libraries from it as code
Files in the dependencies directory	644, owned by root	Write access to any of them is code execution as the service account

The Relay client creates and maintains every path in this table except the dependencies directory. That one is yours to create and maintain: keep it, and everything in it, owned by root and writable only by root.

Custom paths

Override the default directories when installing the Relay client.

sudo ./relay start --config-file /path/to/config.txt \
  --accept-license-agreement \
  --bin-dir /opt/mycompany/bin \
  --data-dir /opt/mycompany \
  --logs-dir /opt/mycompany

Flag	Default	Description
--bin-dir	/usr/local/bin	Directory for the shared binary
--data-dir	/var/lib	Root for configuration data
--logs-dir	/var/log	Root for log files; can be changed with restart

The Relay client appends uipath-relay/ under the custom data and log roots:

--bin-dir  /opt/mycompany/bin  =>  /opt/mycompany/bin/relay
--data-dir /opt/mycompany      =>  /opt/mycompany/uipath-relay/groups/<id>/
--logs-dir /opt/mycompany      =>  /opt/mycompany/uipath-relay/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) derive paths automatically from the installed service configuration.

Proxy configuration

If your network routes outbound traffic through a proxy, export the proxy environment variables before running relay start. Use sudo -E to preserve the environment when elevating:

export HTTPS_PROXY="http://proxy.corp.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.corp.example.com"
sudo -E ./relay start --config "<your-config>" --accept-license-agreement

Without -E, sudo resets the environment and proxy settings are lost.

The Relay client writes the captured proxy variables as Environment= directives in the systemd unit file, so the background service uses them, not system-wide /etc/environment.

To update the proxy after installation: export the new values and run sudo -E relay restart <id>.

To remove the proxy: unset HTTPS_PROXY HTTP_PROXY NO_PROXY, then sudo relay restart <id>.

To verify what the service uses: systemctl cat relay-<id> | grep -i environment.

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

Security frameworks

If your environment uses SELinux, AppArmor, or fapolicyd, ensure the Relay client binary and its data directories are permitted.

If you enable the on-prem executor, the Relay service also runs the Java executable and loads native libraries from the dependencies directory. Allow both, or the executor fails to start or cannot load its connector libraries.

SELinux

# Check enforcement mode
getenforce

# Relabel the binary if a custom policy blocks it
sudo semanage fcontext -a -t bin_t '/usr/local/bin/relay'
sudo restorecon -v /usr/local/bin/relay

When the on-prem executor is enabled, the Relay service also runs the Java executable and loads native libraries from the dependencies directory. Label only the paths that generate denials. Check for denials first.

sudo ausearch -m AVC -ts recent | grep -i -e relay -e java

If the denials show the Java process refused read or map access to the dependencies directory, label the native libraries as shared libraries.

sudo semanage fcontext -a -t lib_t '/opt/uipath/relay/executor-deps(/.*\.so(\..*)?)?'
sudo restorecon -Rv /opt/uipath/relay/executor-deps

For any remaining denials, build a policy module rather than disabling enforcement.

sudo ausearch -m AVC -ts recent | audit2allow -M uipath-relay-executor
sudo semodule -i uipath-relay-executor.pp

AppArmor

Ensure no profile restricts /usr/local/bin/relay from network access or file writes to /var/lib/uipath-relay/ and /var/log/uipath-relay/. If you use custom paths, substitute accordingly.

If your organization confines local services with its own AppArmor profiles and the on-prem executor is enabled, the profile covering the Relay binary must also allow it to execute the Java runtime, and allow the Java process to read and map the connector libraries in the dependencies directory. Check for denials with sudo journalctl -k | grep -i apparmor.

fapolicyd

sudo fapolicyd-cli --file add /usr/local/bin/relay
sudo fapolicyd-cli --update

When the on-prem executor is enabled, fapolicyd must also trust the Java executable, the executor runtime JAR, and each connector library. A Java runtime installed from an archive rather than a distribution package is not in the package database and is untrusted by default; a packaged runtime such as java-21-openjdk needs no entry.

Trust each file individually.

sudo fapolicyd-cli --file add <java-home>/bin/java
sudo fapolicyd-cli --file add /var/lib/uipath-relay/groups/<id>/onprem-executor.jar
sudo fapolicyd-cli --file add /opt/uipath/relay/executor-deps/sapjco3.jar
sudo fapolicyd-cli --file add /opt/uipath/relay/executor-deps/sapidoc3.jar
sudo fapolicyd-cli --file add /opt/uipath/relay/executor-deps/libsapjco3.so
sudo fapolicyd-cli --update

Re-run fapolicyd-cli --file update <path> and fapolicyd-cli --update after any upgrade that replaces a trusted file: a Relay client upgrade, which replaces onprem-executor.jar, a Java upgrade, or a new connector library version. Trust entries record each file's size and hash, so they stop matching once a file changes. If the executor fails to start on a host running fapolicyd, check sudo journalctl -u fapolicyd -n 50.

Paths to allow

Type	Default path
Binary	/usr/local/bin/relay
Data	/var/lib/uipath-relay/
Logs	/var/log/uipath-relay/
Java executable (on-prem executor only)	The java path resolved from PATH, or <java-home>/bin/java
Connector libraries (on-prem executor only)	The directory passed to --onprem-executor-dep-dir

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

User mode

User mode (--user-mode) installs the Relay client as a systemd user service instead of a system service, allowing it to run without sudo. This is suitable for shared machines and restricted environments where root access is unavailable.

Requirements

Requirement	Details
systemd 229+	Verify: systemctl --version
Home directory	Must exist and be owned by the target user
systemd user session	Verify: systemctl --user is-system-running returns running or degraded
SSH login	Required. su / sudo su do not provide the D-Bus session that user services need
loginctl linger	Required for the service to persist after logout and start at boot

Enable linger (one-time, requires admin):

sudo loginctl enable-linger <username>

Without linger, user services stop when you log out and do not start at boot.

Start in user mode

./relay start --user-mode --config-file /path/to/config.txt --accept-license-agreement

On-prem executor in user mode

In user mode the executor runs as your user account instead of root, and the same executor flags apply:

./relay start --user-mode --config-file /path/to/config.txt \
  --accept-license-agreement \
  --enable-onprem-executor \
  --onprem-executor-java-home <java-home> \
  --onprem-executor-dep-dir <dep-dir>

The dependencies directory must not be group- or world-writable. If an administrator is available, have them create it owned by root with read access for your account, so no unprivileged account can change what the executor loads. Otherwise, create it yourself with chmod 0755 on the directory and 0644 on the files.

User mode directory layout

~/.local/bin/
  relay                                      # Shared binary (755)

~/.local/share/uipath-relay/
  groups/<id>/
    client_config                            # OAuth credentials (encrypted, 600)
    metadata.json                            # Service metadata (644)
    .credentials.key                         # Encryption key (600)
    onprem-executor.jar                      # Executor runtime when enabled (600)
  logs/<id>/
    relay.log
    relay.YYYYMMDD-HHMMSS.log
    onprem-executor.log                      # Executor log when enabled

~/.config/systemd/user/
  relay-<id>.service                         # Systemd user unit file

The ~/.config/systemd/user/ path cannot be overridden. Binary, data, and log paths can be customized with --bin-dir, --data-dir, and --logs-dir.

Management commands in user mode

All commands work without sudo:

relay list
relay stop <id>
relay restart <id>
relay delete <id>
relay logs <id> -f

When to use user mode

Scenario	Recommended
Production server with root access	System mode (default)
Shared machine, no root access	User mode
Development or testing	User mode
Security-sensitive environments	System mode (tamper-proof binary path)

Uninstall

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

   sudo relay delete <id>
   

2. Remove the shared binary:

   sudo rm /usr/local/bin/relay
   

3. Remove remaining data and log directories:

   sudo rm -rf /var/lib/uipath-relay /var/log/uipath-relay
   

For user mode, replace the commands with the user-mode equivalents (no sudo) and remove ~/.local/bin/relay and ~/.local/share/uipath-relay.

Troubleshooting

Symptom	Cause	Resolution
Service fails to start	Insufficient permissions	Run with sudo
permission denied	Cannot create directories	Verify sudo access, or use custom paths to a writable location
systemctl: command not found	systemd not installed	Use foreground mode (--detach=false) or install systemd
Service starts then stops immediately	Configuration or network error	Check relay.log for startup errors
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
SELinux or AppArmor blocking execution	Security framework policy	See Security frameworks
XDG_RUNTIME_DIR not found (user mode)	Not logged in via SSH	Log in via SSH, or enable linger
D-Bus session bus unreachable (user mode)	Not logged in via SSH	Log in via SSH, or enable linger
Proxy not used by service	Variable not captured at start	Re-run with sudo -E, or verify with systemctl cat relay-<id> | grep -i environment
High CPU or memory	Log level set to trace or debug	Set log level to info or higher

Diagnostic commands

# Real-time logs
sudo relay logs <id> -f

# Systemd journal
journalctl -u relay-<id> -f

# Service status
systemctl status relay-<id>

# Connectivity test
nc -zv cloud.uipath.com 443

# Required only for Relay client versions earlier than 26.4.2
nc -zv <region>-relay.uipath.com 443

# Check if binary is blocked by SELinux
sudo ausearch -m AVC -ts recent

# Check AppArmor status
sudo aa-status

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

Quick reference

Action	Command
Start	sudo relay start --config-file config.txt --accept-license-agreement
Stop	sudo relay stop <id>
Restart / upgrade	sudo relay restart <id>
Delete	sudo relay delete <id>
Delete (force)	sudo relay delete <id> --force
List	relay list
Describe	relay describe <id>
Logs	relay logs <id> -f
Service status	systemctl status relay-<id>
Systemd journal	journalctl -u relay-<id> -f