RealTimeX Link

RealTimeX Link is this computer's always-on companion for RealTimeX. Its first feature is Remote control hosting: it lets your other computers, and people you choose, see and control this one, the way a VNC server does. RealTimeX itself is the app you control other computers from.

• rtx-linkd (crates/linkd): the daemon. This computer's App ID, password and connected computers, connection requests, the listener other computers reach over Tailscale, and its own Public Exposure relay (relay.rs), so computers outside the tailnet reach it through https://x.realtimex.ai/d/<App ID>. It keeps running when the window is closed.
• rtx-link (crates/link): the window and the menu bar / tray icon. Closing the window keeps hosting; Quit stops it. rtx-link --background (at login, or when RealTimeX starts Link) shows only the icon. On Linux the icon is a process of its own and each opened window another, since a window hidden on Wayland cannot be shown again.
• rtx-control (crates/control): the desktop helper rtx-linkd starts, installed next to it: screenshots, the WebRTC live view, mouse and keyboard input and the clipboard, as JSON lines on stdin/stdout (crates/control/src/control.rs). rtx-control --check prints one JSON line, {"tool":"rtx-control","version":"0.1.0","protocol":2,"platform":"macos","input":true}, and exits 0 when this platform has input. It posts input but never reads the keyboard. Physical keys (0.2.4, realtimex-link#7, realtimex-ai-app#2909): a live view sends {type:"key", code, down, repeat?} with a KeyboardEvent.code, pressed by position (macOS key codes, Windows scancodes, evdev on X11 and Wayland), so this computer's layout and input source decide what it types; info lists the physical-keys feature. Codes Link has no key for are skipped. A view's held keys are released when it closes, loses control, sends a batch that fails or is refused, or sends nothing for 30 s; macOS and Windows post the viewer's repeats, X11 and Wayland repeat on their own. The HTTP actions endpoint takes keys combos only. Which screen (0.5.0, realtimex-link#12): each live view shows the display it chose, and only it (two viewers can watch different screens); a request that names none shows the primary, as before. The live view's info lists displays (feature displays; {id, name, primary, x, y, width, height, scale}, left to right, sizes in native pixels) and the one shown; {type:"select_display", display} switches, letting go of the view's held keys and buttons first; a {type:"displays"} push follows a change, with fallback {from, reason} when the view's display went away and it shows the primary instead. A batch of actions may name its display and is refused with 409 display-changed when that isn't the one shown. Agents: GET /remote-control/displays, and display on /screenshot, /actions and /frames (404 display-not-found; the X-Screen-Display header says which one a picture is). A GNOME Wayland session records every monitor from its start (a stream nobody reads costs nothing measurable) and starts again when a physical monitor is plugged in or out; a headless one records virtualDisplays (1–4, default 1; GET/POST /v1/displays/virtual {count} on the local API) virtual monitors, Meta-0… in the order it made them. For agents (realtimex-ai-app#3055, features errors-v2, windows, wait): every error body is {error, code, retry, retryAfterMs?, delivery?, suggestion?} (retry: safe, after with retryAfterMs and Retry-After, refresh or no; delivery for input: none, unknown or done; codes and their rules in crates/linkd/src/error.rs), a superset of the old {error, code?}; success bodies and the live view's DataChannel are unchanged. GET /remote-control/windows[?display=<id>] lists normal app windows ({id, pid, app, appName, title, display, frame, focused, minimized}, frame in that display's native pixels; ids m: macOS, w: Windows, x: X11, opaque to clients) and POST /remote-control/windows/focus {id} (control) brings one to the front and checks it (window-not-found, focus-refused, input-blocked, permission-missing); GNOME Wayland answers unsupported, a locked screen screen-locked, and the macOS login window has neither. /screenshot adds an x-screen-frame token, and POST /remote-control/wait {display?, since?, timeoutMs?, settleMs?, region?} answers once the screen changed since that picture ({changed, elapsedMs, frame, display, area?}; changed:false at the timeout), from rtx-control's change thumbnail every 250 ms, at most two waits per client. Accessibility (feature ax, realtimex-ai-app#3055 Phase 2): GET /remote-control/ax/apps and POST /remote-control/ax/{snapshot,find,get,act,batch} read and act on app controls by ref through the bundled, pinned agent-desktop CLI (third_party/agent-desktop.json), which rtx-control runs one at a time with hard timeouts. Nodes are Link's own shape (ref, role, name, value?, states, secret?, bounds?, actions, children?; bounds in that display's native pixels); refs belong to the client that got them (15 minutes); a password field's value is never returned (secret:true); reads need view and acts control; a locked screen is screen-locked. type falls back to set-value, then a click and paste, and stops when a step may have landed. Codes: stale-ref, ambiguous-target, no-tree, needs-pixels, app-unresponsive, ax-failed. Each platform is switched in crates/linkd/src/ax.rs (PLATFORMS; RTX_LINK_AX=0|1 overrides on one computer). Every window and app carries appKey (bundle:, pkg:, exe:, flatpak:, snap:, desktop:). Start with this computer on macOS (0.4.1, realtimex-link#11): one administrator's prompt installs a root LaunchDaemon that runs its owner's daemon from boot, and a session agent at the login window and in each user's session, so allowed computers connect at the login window and the lock screen and can sign in there. Turning it off needs no prompt. Background items show under RealTimeX.AI when the main app is installed; with it off in Login Items, turning on is refused and nothing is left installed. After a self-update (0.6.1, realtimex-link#13) the supervisor restarts every session agent from the new copy, and an agent whose executable an update replaced restarts itself. With no session agent at the console, remote control answers 503 no-session-bridge, and GET /v1/status says remoteControl: {available, reason}. Start with this computer (0.3.0, realtimex-link#10, Windows): Link's service (rtx-linkd --service, LocalSystem, installed by the installer) runs its owner's daemon from boot while POST /v1/unattended {enabled:true} is on, so allowed computers connect at the sign-in and lock screens and through UAC prompts; the helper follows the console session and the input desktop, and Ctrl+Alt+Delete is sent with SendSAS. Turning it on needs a local administrator (no UAC prompt). With a roaming or redirected profile it waits until the profile is local at boot. Headless GNOME Wayland (0.2.6, realtimex-link#9): with no monitor attached, the session records a 1920×1080 virtual monitor (Mutter's RecordVirtual) instead of the primary one, and it goes away when the session stops. GNOME refuses remote sessions while the screen is locked ("Session creation inhibited"), so a computer used only remotely needs automatic screen lock off.
• rtx-screens (crates/screens): window and display screenshots, capture only. RealTimeX's recorder uses it too, pinned to a commit of this repo.
• rtx-glibc-compat (crates/glibc-compat): the glibc 2.34 floor on Linux, linked into each executable (use rtx_glibc_compat as _;).

The keyboard boundary (the recorder never reads the keyboard or posts input; rtx-control never reads the keyboard) is checked by RealTimeX against this repo's sources at the pinned commit (native/rtx-capture/scripts/no-keyboard.json there): a new process start, run-time code load, build script or input API in rtx-control or rtx-screens needs review there before RealTimeX moves its pin.

RealTimeX ships RealTimeX Link and manages it from Settings → Sharing → Remote control. Link also works on its own, for a computer that should be controlled from RealTimeX elsewhere without RealTimeX installed here: download it from Releases, sign in to your RealTimeX account in its window and turn on Allow remote control.

Platform	Download	Installs to
macOS	RealTimeX-Link-<version>-macos-<arch>.dmg (signed, notarized): drag it to Applications	/Applications/RealTimeX Link.app
Windows	RealTimeX-Link-Setup-<version>.exe (signed)	C:\Program Files\RealTimeX Link
Linux	realtimex-link_<version>_<arch>.deb / .rpm	/opt/RealTimeX Link

RealTimeX installs Link in the same places, so either one installs or updates it, never a downgrade. Link also updates itself (crates/linkd/src/update.rs): it looks for a newer release at start and every six hours, and the window and tray offer Update. On macOS it installs the signed archive once codesign confirms the same Team ID, then reopens; on Windows it starts the signed installer once Authenticode confirms the same publisher; on Linux it opens the release page. Releases (.gitlab-ci.yml): Link's code lives on rtgit.rta.vn/rtlab/rtwebteam/realtimex-link, and this GitHub repository is its public push mirror; send changes there. Each push runs the GitLab pipeline, which builds on GitHub Actions here (ci/github_build.py). A vX.Y.Z tag (protected, and equal to Cargo.toml's version) builds every platform into a draft release (unsigned archives, Linux packages). GitLab then checks that the files come from the build run of the tag's own commit and takes them from that run's artifacts (ci/release.py fetch), RealTimeX's release runners sign and notarize the macOS builds and make the .dmg (ci/sign-mac.sh) and sign the Windows executables and installer (ci/sign-win.ps1), and the draft is published, as Link's latest unless a newer release is out (ci/release.py).

• Installing: rtx-linkd install DESTINATION installs the Link it belongs to as its own app: /Applications/RealTimeX Link.app, C:\Program Files\RealTimeX Link, /opt/RealTimeX Link (with an applications-menu entry on Linux). It never downgrades, and stops an older Link first. RealTimeX runs it from its installers (Windows, Linux) or at start (macOS).
• At login: GET/POST /v1/autostart on the local API adds or removes a per-user login item (LaunchAgent, Run key, XDG autostart) that starts rtx-link --background. RealTimeX turns it on with its Remote Control plugin and off without it.
• Account: Link signs in to the RealTimeX account itself: Sign in opens the browser at accounts.realtimex.ai (Keycloak client realtimex-link, Authorization Code with PKCE, answered on a one-time 127.0.0.1 port), and Link keeps the offline refresh token sealed and renews its own access tokens (GET /v1/account, POST /v1/account/sign-in, /sign-out). That is for a computer with Link only. When RealTimeX is installed, Link always uses RealTimeX's account (realtimex-ai-app#2836 §6.2–6.3; see account below): its handover replaces Link's own sign-in, and Link's window shows the account read-only, with no Sign out or other account. RTX_LINK_AUTH_ISSUER points at another realm for development.
• Public Exposure (realtimex-ai-app#2836): Link is this computer's only connector to RealTimeX's relay (relay.rs). It enrolls every surface: published artifacts (a), the embed widget (e), webhooks (h), the mobile app (m), desktop messaging (p) and Remote Control (d, served in-process). It runs while Keep RealTimeX Link running is on, whatever "Allow remote control" says, and stays up while RealTimeX is closed. Frames to the relay, request bodies and WebSockets wait in bounded queues, and each surface has a request body limit (below).

Local API for RealTimeX's Public Exposure

The contract agreed with RealTimeX (realtimex-ai-app#2836, loop-briefs/issue-2836-design.md §6). All of it is on the local API (127.0.0.1, the data folder's bearer token, POST /v1/hello first) with JSON bodies; each block is a flag in GET /v1/version's features. Error codes are kebab-case.

• account (the owner RealTimeX, owner.rs):
  • POST /v1/account/token { token, apiBase?, installId }: the first RealTimeX install to hand over with its installId owns Link; its handover always replaces Link's own sign-in. Another install gets 409 adopted-other and changes nothing. Without an installId (an older RealTimeX) the handover is ignored once there is an owner; with none it signs Link in only while Link has no sign-in of its own.
  • When the handed-over account isn't the one the current exposure belongs to (Link keeps that apart from the sign-in, so a sign-out in between doesn't hide a switch), Link drops that exposure and everything shared on it: its credential, install ID and adoption, the artifact, webhook and Shared lists and the origin. It keeps the exposure's ID as a former one, and the window says once that the previous account's links are offline. That account's queued webhook deliveries stay, readable by it alone. The exposure itself stays its owner's; Link retires nothing without its token.
  • POST /v1/account/sign-out { installId } (the owner only): Link is signed out and its relay stops until the next handover. Without an owner it is Link's own sign-out.
  • POST /v1/account/release { installId } (RealTimeX's uninstallers): Link manages its own account again. Link also stops counting RealTimeX as present by itself, checked at its start, when its window opens (GET /v1/account?check=1) and before a sign-out: present while a handover came in the last 24 h; otherwise not when RealTimeX isn't installed, or after 30 days without a handover. GET /v1/account says managedByRealtimex.
• running: GET /v1/running → { on }; POST /v1/running { on }. On by default. Off stops the relay and remote control and removes the login item; the local API keeps answering, so RealTimeX can offer Turn on. Turning it on clears an opt-out made through POST /v1/autostart. RealTimeX turns it on only when the person asks.
• exposure:
  • GET /v1/exposure → { state, appId, installId, account, surfaces: { <surface>: publicBaseUrl }, formerAppIds, error? }. state: off, signed-out, connecting, online or error (then error: { code, message }: relay-error, recovery-capped, or waiting-for-realtimex when enrolling or recovering needs a token only RealTimeX hands over). means connected with every surface enrolled; until then Link keeps enrolling in the background. is enrolled only where the Marketplace allows it.

Build

Rust is pinned in rust-toolchain.toml (rustup installs it).

scripts/build.sh [arm64|x86_64] dist          # macOS (RealTimeX Link.app), Linux
scripts\build.ps1 [x86_64|arm64] dist         # Windows (Visual Studio C++ tools)
cargo test
scripts/test-macos-control.py path/to/rtx-control   # live macOS check of rtx-control

test-macos-control.py drives the protocol, then posts input into its own test window only (test-control-window.swift, after a minute without anyone using the Mac, and only if Accessibility is already granted), including that held keys and buttons are released when a session ends.

rtx-linkd [--data-dir DIR] [--port 7420] prints one JSON line when ready and stops on SIGTERM (or POST /v1/shutdown on its local API). Its data folder is per user: Application Support/RealTimeX Link (macOS), %APPDATA%\RealTimeX Link (Windows), ~/.config/realtimex-link (Linux), or RTX_LINK_DATA_DIR.

License

Apache License 2.0. See LICENSE and NOTICE.