test-cloud

latest

false

Test Cloud admin guide

Last updated May 12, 2026

DELIVERY:

Deploying the Relay client on Linux

This page covers production setup details specific to Linux. For cross-platform prerequisites, networking 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.

Pre-installation checklist

System

Supported Linux distribution with systemd 229+
sudo (root) access — or plan to use --user-mode
Minimum 200 MB free disk space

Network

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

Security

SELinux / AppArmor / fapolicyd exclusions configured (if applicable) — see Security frameworks

Configuration

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

Validation commands:

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

# Verify sudo access
sudo -v

# Check available disk space
df -h /var/lib
# Check systemd version (must be 229+)
systemctl --version

# Verify sudo access
sudo -v

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

Install

1. Download and extract

Architecture	Archive
x86_64	relay-linux-amd64.zip
ARM64	relay-linux-arm64.zip

unzip relay-linux-amd64.zip && chmod +x relay
unzip relay-linux-amd64.zip && chmod +x relay

2. Start

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:

sudo ./relay start --config "<your-config>"
sudo ./relay start --config "<your-config>"

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

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

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
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
sudo relay logs <id> -f

Manage

List

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

relay list
relay list --json
relay list
relay list --json

Stop

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

sudo relay stop <id>
sudo relay stop <id>

Restart and upgrade

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

sudo relay restart <id>
sudo relay restart <id>

Binary upgrade: download the new relay binary and run sudo ./relay 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.

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`
Binary upgrade	Download new binary, then `sudo ./relay restart <id>`

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>
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
sudo relay delete <id> --force

Version

relay version
relay version

There is no auto-upgrade. To update, download the new binary and run sudo ./relay restart <id> 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)

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

/etc/systemd/system/
  relay-<id>.service                         # Systemd unit file
/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)

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

/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)
`relay.log`	`644`	Readable for troubleshooting
Binary	`755`	Executable by systemd

Custom paths

Override the default directories at install time:

sudo ./relay start --config-file /path/to/config.txt \
  --bin-dir /opt/mycompany/bin \
  --data-dir /opt/mycompany \
  --logs-dir /opt/mycompany
sudo ./relay start --config-file /path/to/config.txt \
  --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

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

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

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.

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

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.

fapolicyd

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

Paths to allow

Type	Default path
Binary	`/usr/local/bin/relay`
Data	`/var/lib/uipath-relay/`
Logs	`/var/log/uipath-relay/`

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

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)
  logs/<id>/
    relay.log
    relay.YYYYMMDD-HHMMSS.log

~/.config/systemd/user/
  relay-<id>.service                         # Systemd user unit file
~/.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)
  logs/<id>/
    relay.log
    relay.YYYYMMDD-HHMMSS.log

~/.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
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

Delete all Relay clients (use relay list to see installed groups):
```
sudo relay delete <id>
sudo relay delete <id>
```

Remove the shared binary:

sudo rm /usr/local/bin/relay
sudo rm /usr/local/bin/relay

Remove remaining data and log directories:

sudo rm -rf /var/lib/uipath-relay /var/log/uipath-relay
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 TLS passthrough
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 <region>-relay.uipath.com 443

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

# Check AppArmor status
sudo aa-status
# 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 <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`
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`
Logs	`relay logs <id> -f`
Service status	`systemctl status relay-<id>`
Systemd journal	`journalctl -u relay-<id> -f`

Was this page helpful?

PREVIOUSDeploying the Relay client

NEXTWindows setup

Test Cloud admin guide

Operating system requirements​

Pre-installation checklist​

System​

Network​

Security​

Configuration​

Install​

1. Download and extract​

2. Start​

3. Verify​

Manage​

List​

Stop​

Restart and upgrade​

Delete​

Version​

Directory structure​

File permissions​

Custom paths​

Proxy configuration​

Security frameworks​

SELinux​

AppArmor​

fapolicyd​

Paths to allow​

User mode​

Requirements​

Start in user mode​

User mode directory layout​

Management commands in user mode​

When to use user mode​

Uninstall​

Troubleshooting​

Quick reference​