- 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
- 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.
| Protocol | Port | Destination | TLS passthrough required | Purpose |
|---|---|---|---|---|
| HTTPS | 443 | cloud.uipath.com | Not required | Authentication and relay registration |
| TCP | 443 | <region>-relay.uipath.com | Required | Persistent tunnel to the relay server (raw TLS-wrapped TCP) |
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 |
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.
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.
Configure your firewall and any TLS-inspecting proxy or DLP appliance to allow TLS passthrough for <region>-relay.uipath.com:443. TLS inspection on this destination 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 framing.
Verify connectivity
Before installing the Relay client, confirm that outbound traffic on port 443 is allowed to both required destinations.
Linux:
nc -zv cloud.uipath.com 443
nc -zv <region>-relay.uipath.com 443
nc -zv cloud.uipath.com 443
nc -zv <region>-relay.uipath.com 443
Windows (PowerShell):
Test-NetConnection -ComputerName cloud.uipath.com -Port 443
Test-NetConnection -ComputerName <region>-relay.uipath.com -Port 443
Test-NetConnection -ComputerName cloud.uipath.com -Port 443
Test-NetConnection -ComputerName <region>-relay.uipath.com -Port 443
A successful result shows TcpTestSucceeded : True on Windows and succeeded on Linux. If either check fails, review your firewall rules and 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.
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 |
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.
Management commands
| Action | Linux | Windows (Admin PowerShell) |
|---|---|---|
| List Relay clients | relay list | .\relay.exe list |
| List (JSON output) | relay list --json | .\relay.exe list --json |
| View logs | relay logs <id> | .\relay.exe logs <id> |
| Stream logs | relay logs <id> --follow | .\relay.exe logs <id> --follow |
| Reload configuration | relay reload <id> | .\relay.exe reload <id> |
| Stop | sudo relay stop <id> | .\relay.exe stop <id> |
| Restart | sudo relay restart <id> | .\relay.exe restart <id> |
| Delete | sudo relay delete <id> | .\relay.exe delete <id> |
| Force delete | sudo relay delete <id> --force | .\relay.exe delete <id> --force |
| Version | relay version | .\relay.exe version |
Use --force on delete when credentials are unreadable — for example, after a VM clone or reimage — or when the cloud-side relay group has already been deleted.
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. 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.-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 <id>
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):
--config/--config-file— replace the client configuration.--log-level— change the log level.--heartbeat-interval— change the heartbeat interval. Pass0to leave unchanged.--reconnect-interval— change the proactive reconnect interval. Minimum1800(30 minutes) when set. Pass0to disable.
relay logs <id>
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, group ID, creation timestamp, and service mode.
--json— emit JSON output for automation and scripting.
relay reload <id>
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 <id>
Stop the Relay client service. Configuration and credentials are preserved — the Relay client can be restarted later.
relay delete <id>
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. 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 |
- 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
- Setup guides
- Operations
- Connection resilience
- Proactive reconnect
- Reload configuration
- Logging
- Management commands
- Command reference
relay startrelay restart <id>relay logs <id>relay listrelay reload <id>relay stop <id>relay delete <id>relay support-bundle [id]relay version- Antivirus and endpoint security