# Remote Session — Live Authoring and Remote Debug/Run on an Orchestrator Unattended Robot The `uip rpa remote` group connects the local project to a remote robot — an Orchestrator unattended robot — and operates on it: configure the target, open and close the remote session, execute shell commands, transfer files both ways. Every remote operation acts on the **configured remote target**, stored per project by `remote configure`. ## When to Use - **Design a workflow on a remote machine** — the target application exists only on the remote machine, or UI-heavy design should run there so the user's own machine stays free → **Live Authoring**. Live Authoring is a superset of Remote Run Only: in the same session, also debug/run the workflow on the remote machine — do NOT switch to Remote Run Only for that. - **Only debug/run a locally designed workflow on a remote machine** (no remote design work, no Live Authoring target configured) → **Remote Run Only**. Authoring is unchanged: create, edit, and validate the workflow locally per the normal skill workflow. ## Remote Session Modes The mode is set on `remote configure` with `--live-authoring` or `--remote-run-only`. | | Live Authoring (`--live-authoring`) | Remote Run Only (`--remote-run-only`) | |---|---|---| | Connection | Persistent — one long-lived remote session job on the robot | None | | Debug / run with `--remote` | Executes on the remote machine, over the session | Each run/debug session is an Orchestrator job of its own | | `remote exec`, `remote upload-file`, `remote download-file` | Served by the session — return in seconds | Use Live Authoring | | Remote UI Automation (the `uip rpa uia` group in remote mode — syntax in the UIA docs), remote screen streaming | Available | Not available | | `remote start` / `remote stop` | Open / close the session | Not applicable — `remote start` fails | | Default | — | Yes, for a target that never had a mode stored | Choose the mode: 1. **Live Authoring** when the workflow is designed on the remote machine — the target application exists only there, or the design work should not occupy the user's machine. It covers everything Remote Run Only does: debug/run with `--remote` executes on the remote machine over the session. 2. **Remote Run Only** when the workflow is designed locally and only debug/run must happen on the robot. 3. **Never downgrade Live Authoring to Remote Run Only to debug/run.** When the stored mode is Live Authoring, keep it — debug/run within it. The two flags are mutually exclusive. Passing neither keeps the stored mode. Switching from Live Authoring to Remote Run Only releases the session. ### Live Authoring Known Limitations 1. Live Authoring is unavailable on Serverless robots. 2. Live Authoring is unavailable on attended robots. 3. Live Authoring is unavailable on robots that can run only background jobs. When the intended target is one of these, tell the user Live Authoring is not supported on it and ask for a different target (Rule 3). ## Critical Rules 1. **Run `uip rpa remote status` first, at the start of every task.** It is read-only. If the stored target already matches the intended folder/machine/robot/runtime and mode (a Live Authoring target also matches a debug/run-only task), do NOT reconfigure — in Live Authoring with `remoteSessionEnabled: true` the session is already open: proceed directly to the work, no `remote start`; in Live Authoring with `remoteSessionEnabled: false` run `uip rpa remote start`; in Remote Run Only proceed directly to debug/run. Configure only when no target is stored or it differs (§ Session Lifecycle). 2. **IMPORTANT — always pass `--robot` on `configure`.** The CLI lists it as optional (falls back to the machine's default identity), but the remote connection does not work without it. In Live Authoring, `configure` itself fails with `Could not start remote debug session. Foreground process requires you to have an unattended robot with credentials defined`; in Remote Run Only, `configure` succeeds and every later operation fails with that error. Either way the broken target (`robot: null`) is stored — reconfigure with `--robot`. 3. **Ask the user which target to use.** Unless the user already named the folder/machine/robot/runtime, look up the candidates from Orchestrator with the uip CLI and ask which to use — never silently pick one (§ Discovering Option Values). 4. **Pass the mode flag explicitly on every `configure`.** Pick `--live-authoring` or `--remote-run-only` from § Remote Session Modes; do not rely on whatever mode is stored. Live Authoring is a superset of Remote Run Only — when the target is in Live Authoring, debug/run there and never reconfigure it to `--remote-run-only`. 5. **Always run `uip rpa remote stop` when Live Authoring work is finished** — also when abandoning the task or after an unrecoverable error. The session job holds an unattended runtime on the robot; on a machine with a single unattended runtime it blocks every other job until it is stopped. `stop` MUST be the last remote command. 6. **Orchestrator sign-in required.** On `not authenticated` / `401` / `403`, sign in with the uip CLI per [cli-reference.md § Authentication](cli-reference.md#authentication), then retry. 7. **The remote filesystem is not directly accessible — transfer first.** To read a remote file, `download-file` it and read the local copy. To use a local file on the remote machine, `upload-file` it first and reference the remote path. Always use absolute remote paths. 8. **`exec` verdict = the trailing JSON envelope.** The command's stdout and stderr stream to local stdout ahead of the envelope; read the command output from the streamed lines and the verdict from `Result` / `Message` only (§ Execute a Shell Command on the Remote). 9. **Use `--output json`** on every command whose output is parsed, and **pass `--project-dir ""` on every `uip rpa remote` command.** The target is stored per project; without the flag the current directory is used, and outside a project folder every command fails with `Not a UiPath project at '': project.json is missing.` 10. **Run/debug verdict = outer `Result` / inner `HasErrors`** — same as local runs, never log-entry levels (SKILL.md Common Rule 8a). ## Session Lifecycle 1. **Check** the stored target (Rule 1): ```bash uip rpa remote status --project-dir "" --output json ``` 2. **Already configured and matching** — `target` is `UnattendedRobot`; folder/machine/robot/runtime and `liveAuthoring` match the intent; `liveAuthoring: true` matches a debug/run-only task too (§ Reading `remote status`): - Live Authoring, `remoteSessionEnabled: true` → the session is already open; trust `status` and proceed to step 4 — do NOT run `remote start`. If a later remote command reports that no session is open, run `remote start` then and retry the command. - Live Authoring, `remoteSessionEnabled: false` → open the session: ```bash uip rpa remote start --project-dir "" --output json ``` - Remote Run Only → nothing to start; proceed to § Debug / Run a Workflow on the Remote. 3. **Not configured, or different** → `remote configure` (§ Configure a Remote Target). In Live Authoring, `configure` also opens the session — no separate `start` needed. 4. **Work** — debug/run with `--remote`; in Live Authoring also `exec`, `upload-file`, `download-file`, and remote UI Automation. 5. **Finish (Live Authoring)** — close the session (Rule 5): ```bash uip rpa remote stop --project-dir "" --output json ``` The target stays stored. Next task: step 2 applies — `status` shows `remoteSessionEnabled: false`, so `remote start` reopens the session without reconfiguring. | Command | Behavior | |---|---| | `configure` | Resolves and stores the target and mode, then connects. In Live Authoring it blocks until the session job is running — tens of seconds; do not wrap it in a short timeout. Reconfiguring replaces the stored target. A `configure` that fails to resolve a name (folder, machine, robot, runtime) keeps the previous target and leaves a running session untouched; one that fails while connecting (e.g. missing `--robot`) stores the new target | | `start` | Opens the Live Authoring session → `"Remote session ready."`. No-op when the session is already open. Fails with no target (`Remote debugging is not configured for an unattended robot…`) or in Remote Run Only (`The remote connection is in Remote Run Only mode…`) | | `stop` | Closes the session and releases the robot → `"Remote session stopped."`. Always succeeds — also when no session is running or no target is configured | | `status` | Read-only — changes nothing, starts nothing | ## Reading `remote status` ```json { "Result": "Success", "Code": "ToolResult", "Data": { "success": true, "target": "UnattendedRobot", "remoteSessionEnabled": true, "liveAuthoring": true, "folder": "", "robot": "", "machine": "", "runtime": "" } } ``` | Field | Meaning | |---|---| | `target` | `UnattendedRobot` — a remote target is in effect. `LocalMachine` — no target (not configured, or the backend restarted); the other fields are then absent | | `remoteSessionEnabled` | `true` after `configure` / `start` — the session is open, skip `remote start`; `false` after `stop` — run `remote start` before remote work | | `liveAuthoring` | `true` — Live Authoring; `false` — Remote Run Only | | `folder`, `machine` | Resolved folder path and machine name | | `robot` | Resolved robot name — may differ from the account name passed to `--robot`. `null` means `--robot` was omitted: reconfigure with it (Rule 2) | | `runtime` | Pinned host as ` - \`; `null` when `--runtime` was omitted and Orchestrator picks the connected session | ## Configure a Remote Target ```bash uip rpa remote configure \ --folder-path "" \ --machine "" \ --robot "" \ --live-authoring \ --project-dir "" --output json ``` Pinned to one host of a machine template (§ When to Pass `--runtime`): ```bash uip rpa remote configure \ --folder-path "" \ --machine "" \ --robot "" \ --runtime "" \ --live-authoring \ --project-dir "" --output json ``` | Flag | Required | Value | |------|----------|-------| | `--machine` | Yes | Orchestrator machine name to run the unattended robot on | | `--robot` | **Yes** | Robot/user account name to run as; resolved to the robot in the folder. Listed as optional, but operations fail without it (Rule 2) | | `--folder-path` | No | Fully-qualified Orchestrator folder path the machine/robot belong to (e.g. `Shared/Finance`). Defaults to the backend's current folder — pass it whenever the user named a folder | | `--runtime` | No | Connected host of the machine to pin the session to: the host machine name (case-insensitive) or the full ` - \` label. Ignored for serverless machines. Omitted → Orchestrator picks the connected session | | `--live-authoring` / `--remote-run-only` | One of them (Rule 4) | Session mode — § Remote Session Modes | ### When to Pass `--runtime` 1. **Pass it when the machine has more than one connected host and the work depends on a specific one** — typically Live Authoring where the target application is installed on only one host, or when the user names a host. Without it, Orchestrator may open the session on another host. 2. **Omit it when the machine has a single connected host** — Orchestrator picks that one. 3. **Never guess the host name.** Look up the connected hosts per § Discovering Option Values. A wrong name fails with an error that lists the machine's connected runtimes — offer those to the user (Rule 3). ### Discovering Option Values Look up each value the user has not named with these read-only commands, in order. Skip step 1 when the user already named the folder. 1. **Folder** — the `--folder-path` value is `Path` (fully qualified, e.g. `Shared/Finance`), not `Name`: ```bash uip or folders list --output json ``` Lists the folders the signed-in user can access; add `--all` to list every folder in the tenant. 2. **Remote targets in the folder** — robots, machines, and hosts in one call: ```bash uip rpa remote targets --folder-path "" --project-dir "" --output json ``` Example output (trimmed): ```json { "success": true, "folder": "Shared", "robots": [ { "name": "", "enabled": true, "hasCredentials": true } ], "targets": [ { "machine": "", "host": "", "status": "Available" }, { "machine": "", "host": "", "status": "Disconnected" } ] } ``` | Field | Use | |---|---| | `robots[].name` | `--robot` value. Offer only robots with `enabled: true` and `hasCredentials: true` — a disabled or credential-less robot passes `configure` and fails at session start | | `targets[].machine` | `--machine` value. One row per host, so a machine with several hosts appears in several rows | | `targets[].host` | `--runtime` value, passed as-is | | `targets[].status` | `Available` — usable host; `configure` takes only an `Available` host as `--runtime`. `Serverless` — serverless machine: Remote Run Only (§ Live Authoring Known Limitations), `--runtime` does not apply. `Busy`, `Disconnected`, `Unresponsive`, `NoSession`, `Unknown` — not usable now; `Disconnected` means that host's robot service is not connected to Orchestrator | The number of `Available` hosts per machine decides whether to pass `--runtime` (§ When to Pass `--runtime`). When the user already named the robot or machine, narrow the listing: `--robot ""` lists only the machines that robot can use and the hosts that serve it — the same check `configure --robot` runs; `--machine ""` lists only that machine's hosts. Then apply Rule 3: present the candidates and ask the user which to use. Offer only machines with at least one `Available` host — `configure` rejects a machine with no connected host; for Remote Run Only, `Serverless` machines are usable too. Empty `robots`, or no usable row in `targets`, means the folder has no usable robot or host; ask the user for another folder. On `not authenticated` / `401` / `403`, sign in per Rule 6 and retry. ### Configure Errors | Message | Fix | |---|---| | `Folder '' not found. Available folders: …` | Pick from the listed folders | | `Machine '' not found in folder ''. Available machines: …` | Pick from the listed machines, or correct `--folder-path` | | `Machine '' has no available unattended session in folder '' - last reported state: …` | No host of that machine is connected. Ask the user to start the machine and connect its robot service to Orchestrator, or pick another machine | | `Robot/user '' not found in folder ''.` | Re-list the robots in that folder (§ Discovering Option Values, step 2) | | `Connected runtime '' not found for machine ''. Available runtimes: …` | Pick from the listed runtimes. An empty list means no host of that machine is connected — handle as the "no available unattended session" row | | `--live-authoring and --remote-run-only are the two modes of one connection; pass at most one.` | Pass exactly one mode flag | | `Could not start remote debug session. Foreground process requires you to have an unattended robot with credentials defined` — from `configure` in Live Authoring, or from later operations in Remote Run Only | `--robot` was omitted — reconfigure with it (Rule 2) | | Later operations fail: `Remote debugging is not configured for an unattended robot…` | No target is stored — run `configure` | | Any `remote` command: `…HelmProjectLoadException: "Not a UiPath project at '': project.json is missing…"` | `--project-dir` is missing or wrong — pass the folder containing `project.json` (Rule 9) | ### Validate After Configuring 1. Check `remote status` (§ Reading `remote status`): `target` is `UnattendedRobot`, `liveAuthoring` matches the chosen mode, and folder/machine/robot/runtime match what was requested. 2. **Live Authoring** — smoke-test end to end and confirm the host: ```bash uip rpa remote exec --command "hostname" --timeout 60 --project-dir "" --output json ``` `Result: Success` proves the session executes commands; the streamed host name must match the pinned `--runtime` when one was set. The call returns in a few seconds when the session is open; 20+ seconds means the command had to start a new session job. 3. **Remote Run Only** — the first `--remote` run (§ Debug / Run a Workflow on the Remote) is the end-to-end check. ## Debug / Run a Workflow on the Remote Add `--remote` to `run` or `debug start` — the workflow executes on the configured unattended robot instead of locally: ```bash uip rpa run --file-path "" --remote --project-dir "" --output json uip rpa debug start --file-path "" --remote \ --breakpoints 'workflowFile=Main.xaml,activityIdRef=Assign_1' \ --project-dir "" --output json ``` `--remote` affects **start commands only** (`run`, `debug start`, plus the Studio Desktop verbs `debug start-from-here` / `debug test-activity`). Mid-session verbs (`debug step-over`, `debug continue`, `debug state`, `execution cancel`, …) operate on the active session and take no `--remote`: ```bash uip rpa debug continue --output json uip rpa execution cancel --output json ``` - **Live Authoring** — run/debug travel over the open session. After a `stop`, run `remote start` before the next `--remote` run. - **Remote Run Only** — every `--remote` run or debug session is an Orchestrator job of its own; nothing to start or stop. - The debug loop is unchanged from local debugging — breakpoints by `activityIdRef`, `DebugState` branching (`Paused` / `Suspended` / `Completed` / `Running`), locals in `DebugDetails`. Full loop: [debugging.md](debugging.md). - Works with both Studio and Helm backends. - `--profiling-mode stream` is ignored when running remote; end-of-run profiling delivery still applies. - To read files the run produced on the robot (logs, screenshots, reports), download them (§ Transfer Files). ## Execute a Shell Command on the Remote Use in Live Authoring with the session open. Runs through the remote OS shell — `cmd.exe /c` on Windows, `/bin/sh -c` otherwise — as the robot's account, so profile paths resolve to that account's profile. ```bash uip rpa remote exec --command "" --timeout \ --project-dir "" --output json ``` | Flag | Required | Value | |------|----------|-------| | `--command` | Yes | Shell command line to run (e.g. `dir` on Windows, `ls -la` on Linux). With a restored package, may be a path relative to the package folder (e.g. `tools\\app.exe --flag`) | | `--package-id` | No | NuGet package id to restore on the remote machine before running the command. Requires `--package-version` | | `--package-version` | No | Version of `--package-id` to restore. Required when `--package-id` is set | | `--working-directory` | No | Working directory for the command. Defaults to the restored package folder when a package is restored, otherwise the Robot installation directory on the remote machine | | `--timeout` | No | Seconds after which the remote command is killed. Omit for no timeout — set one for any command that could hang | Reading the result (Rule 8): - The command's stdout and stderr stream to local stdout **before** the JSON envelope; the envelope's `Data.output` is empty. Take the command output from the streamed lines and parse only the trailing envelope — never feed the whole stdout to a JSON parser. - stdout and stderr arrive merged, and their relative order is not preserved — do not rely on line order across the two streams. - Exit code 0 → `Result: Success`, `hasErrors: false`. - Non-zero exit → `Result: Failure`, `Message` contains `Command exited with code .`, and the CLI process exits 1. - Timeout → `Result: Failure`, `Message` contains `Command timed out.` On a Windows robot use `cmd.exe` syntax (`&&`, `type`, `dir`, `rmdir /s /q`); run PowerShell as `powershell -NoProfile -Command "