rdp-cli
Watch, Pause and Take Over an AI Agent’s Remote Desktop
Applies to: 0.1.2 · Windows / macOS · RDP / VNC
Open the session that already exists
An agent uses commands to operate the remote computer. You can open a viewer for that same session whenever you want to see its progress. On Mac, click the menu bar icon and find the current session by name or address; on Windows, use the notification-area menu. Choose the existing session instead of creating a second login.
You can also open it from the command line:
For Windows PowerShell, run these examples from the executable’s folder and replace rdp-cli with .\rdp-cli.exe.
rdp-cli watch --session SESSION --viewer window
For an authorized browser viewer on your LAN or VPN:
rdp-cli watch --session SESSION --viewer web
The public rdp-cli.com website is not this viewer. Browser access belongs to your running session and its access grant.
Observe without taking control
Viewers start read-only. Watch click rings, drag paths, scrolling and typing progress while the agent continues. Text hints do not repeat what was typed, but text may still be visible in the actual remote application: action hints are not automatic screen redaction.
You can disable hints independently in your viewer. The native window uses FX or F8; the browser offers its Actions setting. Multiple viewers can watch at once.
Pause and make a correction
Choose PAUSE to stop normal input. Choose TAKE when you want to use the remote mouse and keyboard yourself. Only one viewer holds human control at a time, and agent input is rejected while it does.
For example, take control of a remote editor, fix one line and inspect your change. You can attempt input on login, Welcome or busy screens too; the application may not respond, but a screen label does not decide for you whether to try.
If you enable an RDP microphone, do so explicitly while controlling the session and approve the system prompt. VNC does not provide this microphone feature.
Give the session back
Choose RELEASE when finished. The microphone stops, and control returns to the available agent identity. If no agent identity is available, the session remains paused. The agent must get a fresh screenshot and observation token before continuing, because your correction may have changed the application.
Ask the agent to verify the corrected line, then proceed from the current screen. It should not replay the action you already completed.
Know what closing a window means
Closing a read-only viewer keeps the remote connection. Closing or losing the viewer that owns control pauses the session instead of allowing unnoticed agent input. Reconnection also requires a fresh observation and explicit handling of the paused state.
For a complete introduction, read the quick start. The feature guide explains session controls, file permissions and the differences between RDP and VNC.
Enhanced commands in rdp-cli
Run rdp-cli --version first. The commands below require agent_execution.contract_version to be 1; older builds can continue using the single-step workflow above.
Replace uppercase placeholders with actual returned values. In Windows PowerShell, use .\rdp-cli.exe from its folder; on macOS or Linux, use the installed command or the executable’s actual path.
Give each agent a name and a turn
Registered agents explicitly hand control to each other. A person can take over through the GUI or web viewer, then hand back to a chosen agent, which observes again before acting.
Registration returns an agent ID and a credential reference. The session owner grants access; the agent uses the returned claim reference and renews its lease explicitly. Human takeover invalidates previous observations, so inspect the screen again after control is returned.
rdp-cli agents register --name Writer
rdp-cli agents grant --session SESSION --id AGENT_ID --permission read --permission control
rdp-cli control claim --session SESSION --agent-id AGENT_ID --agent-ref AGENT_REF
rdp-cli control renew --session SESSION --agent-id AGENT_ID --agent-ref AGENT_REF --claim-ref CLAIM_REF