Déploiement du client de relais

Prérequis du client Relay, exigences minimales et étapes de configuration multi-plateformes pour la connexion de votre réseau sur site à Test Cloud.

Installez et démarrez le client Relay sur une machine à l'intérieur de votre réseau pour établir le tunnel sortant vers Test Cloud. Avant de commencer, configurez un groupe Relay et préparez la chaîne de configuration du client.

Prérequis

Prérequis matériels

Profil	vCPU	RAM	Groupes de relais	Points de terminaison par groupe	Use case
Standard	1	2 GiB	Jusqu’à 10	Jusqu’à 50	La plupart des déploiements
Grande	2	4 GiB	10+	Jusqu’à 50	Environnements à haut débit ou à grande échelle

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.

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

Astuce :

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.

Prérequis pour le disque

Profil	Disque libre minimum
Standard (1 à 10 groupes)	200 Mo
Grand (au moins 10 groupes)	1 Go

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.

Systèmes d'exploitation pris en charge

Architecture	Linux	Windows
x86_64	Pris en charge	Pris en charge
ARM64	Pris en charge	Pris en charge

Configuration requise pour le réseau

Le client de relais nécessite une connectivité sortante uniquement. Aucune règle de pare-feu entrant n’est nécessaire.

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.

Configuration du client de relais	Protocole	Port	Destination	Autorisation TLS requise	Objectif
All Relay client versions	https	443	cloud.uipath.com	Non requis	Authentification et enregistrement du Relay
Client de relais 26.4.2 ou version ultérieure	HTTPS/WSS	443	cloud.uipath.com	Non requis	Tunnel persistant
Versions de client de relais antérieures à 26.4.2	TLS	443	<region>-relay.uipath.com	Requis	Tunnel persistant

Les versions du client de relais antérieures à 26.4.2 continuent de fonctionner avec les noms d’hôte de relais régionaux. Conservez ces noms d'hôtes dans la liste d'autorisation jusqu'à ce que vous passiez au client de relais 26.4.2 ou à une version ultérieure, et que vous vous connectiez via 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	Nom d'hôte du serveur de relais
us	us-relay.uipath.com
UE	eu-relay.uipath.com
Canada	ca-relay.uipath.com
Suisse	ch-relay.uipath.com
Australie	au-relay.uipath.com
Singapour	sg-relay.uipath.com
Japon	jp-relay.uipath.com
Corée du Sud	kr-relay.uipath.com
UAE	ae-relay.uipath.com
Royaume-Uni	uk-relay.uipath.com
Union européenne (région retardée)	gxp-eu-relay.uipath.com
États-Unis (région différée)	gxp-us-relay.uipath.com

Remarque :

Contactez l’assistance UiPath pour confirmer le nom d’hôte du serveur de relais si votre région de locataire n’est pas répertoriée ci-dessus.

Choisissez la région qui correspond à votre région de locataire UiPath Cloud, et non l'emplacement physique du nœud Relay. Par exemple, si votre locataire est enregistré dans la région États-Unis, utilisez us-relay.uipath.com même si le relais s'exécute dans une zone différente. Les configurations du client de relais 26.4.2 qui se connectent via cloud.uipath.com n’utilisent pas ce nom d’hôte régional.

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.

Pour les versions du client Relay antérieures à 26.4.2, configurez votre pare-feu et tout proxy d'inspection TLS ou appareil DLP pour permettre le passage de TLS pour <region>-relay.uipath.com:443 ; l'inspection TLS sur le nom d'hôte du relais régional interrompt le tunnel de relais.

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.

Bande passante

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.

Vérifier la connectivité

Avant d’installer le client de relais, confirmez que le trafic sortant sur le port 443 est autorisé vers les destinations requises pour votre 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

Un résultat réussi affiche TcpTestSucceeded : True sous Windows et succeeded sous Linux. Si une vérification requise échoue, examinez vos règles de pare-feu. Pour les configurations du client de relais 26.4.2 qui se connectent via cloud.uipath.com, confirmez que les mises à niveau de WebSocket sont autorisées; pour les versions de client de relais antérieures à 26.4.2, confirmez que l’authentification unique TLS est configurée pour le nom d’hôte du serveur de relais.

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.

Configurer un proxy (le cas échéant)

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	Objectif
HTTPS_PROXY / https_proxy	URL du proxy (première vérification)
HTTP_PROXY / http_proxy	URL du proxy (de secours)
NO_PROXY / no_proxy	Hôtes ou domaines séparés par des virgules qui contournent le proxy

L’URL du proxy doit utiliser l’un de ces schémas: http://, https://, socks5:// ou ntlm://. Format: scheme://[user:password@]host:port.

Pour les https:// proxys: le client de relais valide le certificat TLS du proxy par rapport au magasin de confiance du système d’exploitation. Si votre proxy utilise une autorité de certification d’entreprise ou auto-signée, ajoutez cette autorité de certification au magasin approuvé de la machine du client de relais avant de démarrer le relais; sinon, l'établissement de la liaison TLS échoue avec une erreur de vérification du certificat.

Pour les configurations 26.4.2 du client Relay qui se connectent via cloud.uipath.com, configurez votre proxy pour autoriser les connexions HTTPS de longue durée et les mises à niveau WebSocket vers cloud.uipath.com:443. Si le proxy inspecte TLS pour cloud.uipath.com, installez l'autorité de certification du proxy dans le magasin de confiance du système d'exploitation utilisé par le client Relay.

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.

Configurer les IP approuvées (le cas échéant)

Si votre organisation restreint l'accès par adresse IP, ajoutez l'IP NAT de la machine exécutant le client Relay à la liste d'IP approuvées dans Administration UiPath. Le trafic sortant du client Relay atteint Test Cloud à partir de cette adresse IP, vous devez donc l'autoriser explicitement.

Pour obtenir des instructions, consultez Ajouter des plages d'adresses IP approuvées.

Accepter le contrat de licence

Avant de démarrer le client de relais, vous devez accepter le contrat de licence. Choisissez l’une des méthodes suivantes:

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

Guides de configuration

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:

Plate-forme	Guide
Linux	Déploiement du client de relais sur Linux
Windows	Déploiement du client de relais sous Windows
Conteneur	Déploiement du client de relais en tant que conteneur

Opérations

Résilience de la connexion

Le client de relais maintient automatiquement le tunnel:

• Pulsation toutes les 30 secondes par défaut (configurable via --heartbeat-interval, minimum 10 secondes). Le délai d'expiration du tunnel est de 3 × l'intervalle des pulsations. Réduisez l'intervalle si votre pare-feu, votre proxy ou NAT abandonne les connexions TCP inactives avant 30 secondes:

  relay start --config "<config>" --heartbeat-interval 10 --accept-license-agreement
  relay restart <id> --heartbeat-interval 10
  

• Reconnexion automatique à la déconnexion à l'aide d'une mise à l'échelle exponentielle du retrait à des intervalles de 20 secondes.
• Redémarrage automatique du service si le processus se bloque, géré par systemd sous Linux et Windows Service Control Manager sous Windows.
• Démarrage automatique du service au redémarrage du système.

Reconnexion proactive

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.

Activez-le avec l'indicateur --reconnect-interval :

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.

• Haute disponibilité. Lorsque plusieurs clients de relais sont déployés dans le même groupe, ils se coordonnent de sorte qu’un seul client se draine à la fois. Le groupe continue de servir le trafic pendant chaque cycle de reconnexion.

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

Recharger la 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.

Journalisation

Paramètre	Valeur (Value)
Niveau par défaut	info
Rotation	Daily
Rétention	7 jours
Fichier journal (Log File)	relay.log (actuel), relay.YYYYMMDD-HHMMSS.log ( pivoté)

Remplacez le niveau de journalisation par défaut par --log-level trace/debug/info/warn/error. Dans le client de relais 26.4.2 ou version ultérieure, la rétention des journaux pivotés a été remplacée par --log-retention-days <days> sur relay start ou relay restart; la rétention minimale est de 7 jours.

Référence de commande

Début du relais

Enregistrez un nouveau client de relais et démarrez-le en tant que service d’arrière-plan.

Contrat de licence (un requis)

• --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 (obligatoire)

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

Ajustement (facultatif)

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

Chemins d'installation non par défaut (facultatif)

• --data-dir <path>: configuration directory.
• --logs-dir <path>: log file directory.
• --bin-dir <path>: binary install directory.

Linux uniquement

• --user-mode: install as a systemd user service (no sudo required, uses XDG paths).

Windows uniquement

• --service-account <DOMAIN\user>: run the Windows service under a specific account. Default is LocalSystem.
• --service-account-password <password>: password for --service-account.

Redémarrage du relais

Arrêtez et redémarrez le service du client de relais. Détecte les fichiers binaires mis à jour et applique les modifications de définition du service. Les indicateurs suivants peuvent être remplacés au moment du redémarrage (tous les indicateurs par défaut seront inchangés, sauf indication contraire):

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

journaux de relais

Afficher la sortie du journal pour un client de relais.

• -f, --follow: stream new log lines continuously.
• -n, --lines <N>: number of lines from the end. Default 50.

liste de Relay

Affichez tous les clients du relais sur cette machine avec le statut, la version, les horodatages de création et de mise à jour, ainsi que le nom du groupe lorsqu'il est disponible. Les noms de groupe longs sont tronqués dans la sortie de la table.

• --json: emit JSON output for automation and scripting, including full group names.

Description du relais (Client de relais 26.4.2 ou version ultérieure)

Affichez des informations détaillées pour un client de relais, y compris l’ID et le nom du groupe, l’ID du secret, le statut, la version, le mode service et le chemin exécutable, la pulsation et les intervalles de reconnexion configurés, le niveau de journalisation, les chemins locaux et les horodatages.

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.

Rechargement du relais

Récupérez la configuration du proxy à partir de Test Cloud et appliquez-la sans redémarrer. Utilisez comme solution de secours si un point de terminaison nouvellement ajouté renvoie 404.

arrêt de Relay

Stop the Relay client service. Configuration and credentials are preserved. The Relay client can be restarted later.

suppression du relais

Arrêtez le service, désinscrivez-vous de Test Cloud et supprimez toutes les configurations et les identifiants locaux.

• -f, --force: remove locally without cloud deregistration. Use when credentials are unreadable or cloud-side resources have already been deleted.

pack d’assistance de Relay [id]

Collectez une archive caviardée de configuration, de journaux et de métadonnées système pour un ticket d'assistance UiPath. Omettez [id] pour regrouper tous les clients de relais sur la machine. Les informations d’identification et les clés de chiffrement ne sont jamais incluses. Voir Collecter un pack d'assistance pour tous les détails.

Version du relais

imprimez la version du client de relais, la date de création et le hachage de validation git.

Sécurité antivirus et des points de terminaison

Si votre organisation exécute un logiciel de protection des points de terminaison, ajoutez des exceptions pour le fichier binaire du relais et son répertoire de données afin d’empêcher le client de relais d’être bloqué ou mis en quarantaine. Pour les configurations du client de relais 26.4.2 qui se connectent via cloud.uipath.com, autorisez cloud.uipath.com:443. Pour les versions du client de relais antérieures à 26.4.2, configurez les proxys d’inspection TLS, les appliances DLP et les systèmes IDS/IPS pour contourner l’inspection pour <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	Protocole	Action
cloud.uipath.com	443	https	Autoriser
<region>-relay.uipath.com	443	TLS	Autoriser + contourner l’inspection TLS pour les versions de client de relais antérieures à 26.4.2