RemoteDesk/packaging/linux

RemoteDesk Linux controlled endpoint

The Linux package installs four Rust processes. Real-time desktop sessions use the Rust WebRTC stack; the package contains no Go transport sidecar.

• remotedesk-agentd: root system service for device identity, WSS pairing/authentication, authorization, user-session registration, and terminal creation.
• remotedesk-agent-session: per-user service that detects Wayland/X11/PipeWire state and registers through authenticated Unix IPC.
• remotedesk-shell-session: private PTY helper. It uses util-linux runuser --login so PAM opens the requested ordinary-user session; UID 0 is always rejected.
• remotedesk-file-session: private upload/download helper. It runs as the authorized ordinary user, confines paths to that user's home, and verifies size plus SHA-256 before committing files.

File protocol minor 4 resumes both directions. Interrupted uploads retain a mode-0600 hidden partial keyed by a transfer ID that binds user, remote path, size, and whole-file hash; the helper reports the measured partial length and atomically replaces the target only after hashing the complete file. Downloads request the measured local hidden-partial length, receive only the remaining range, re-hash the existing prefix plus new bytes, and rename only after the whole-file hash matches. A hash mismatch removes the local partial.

Protocol minor 10 includes the X11 desktop compatibility path, bounded zlib level adaptation, short-lived session resume, bounded H.264 media IPC, presentation-ACK-driven switching from zlib fallback to H.264-only transport, and bounded relative-pointer input. Pairing grants may include desktop; an Xorg user session registers /run/user/<uid>/remotedesk/desktop.sock, captures the root window through X11 GetImage, and injects authorized absolute/relative pointer, five-button mouse, wheel, and keyboard input through XTEST. Real encode timing and presentation ACKs adapt 1..30 FPS pacing without exceeding the requested FPS ceiling; zlib mode also adapts levels 1..6. Native mode stops full zlib frame encoding and transfer only after a frame-boundary confirmation, and returns to zlib on media or decode failure. On transport loss it releases all input and retains the X11 connection and both controllers for 15 seconds behind a rotating token bound to the authenticated Client and Linux user. The Windows helper stores only that token in the current user's Credential Manager so a restarted helper can resume within the lease. The systemd user unit exposes the X11 socket read-only inside its private /tmp. Protocol minor 11 adds the source path for authenticated Wayland Portal authorization, strict PipeWire DMABUF-to-VA-H.264 transport, presentation-ACK pacing, dynamic pipeline rebuilds, and reis EIS input. Minor 12 adds a 15-second Portal/EIS resume lease bound to the authenticated Client fingerprint, Linux user, and rotating token; disconnect releases all input and the old encoder, while resume requires a new authorized WebRTC sender and a new IDR. Minor 15 adds X11/Windows bidirectional UTF-8 text clipboard source with separate clipboard_read and clipboard_write grants, Offer/Request/Data transfer, a 32 KiB bound, canonical Base64, SHA-256 integrity, and loop suppression. Wayland clipboard remains unavailable. Both desktop paths and the new clipboard path still require rebuilt packages and real desktop validation.

After installation, create a short-lived pairing code locally:

sudo remotedesk-agentd pairing-code --allow-user "$USER"

The code expires after five minutes, is stored only as a salted digest, permits five failed attempts, and is consumed after one successful pairing. The pairing request must also sign the server challenge with the submitted Ed25519 client key. The command prints the device public key and TLS certificate SHA-256 fingerprint; the controller must pin the TLS fingerprint before sending the code. Accepting an arbitrary self-signed certificate is not secure. List or revoke clients with:

sudo remotedesk-agentd list-clients
sudo remotedesk-agentd revoke CLIENT_FINGERPRINT

The daemon listens on TCP 39500 by default. Edit /etc/remotedesk/agent.env to change it and restart remotedesk-agentd. The package deliberately does not modify nftables, firewalld, UFW, SELinux, or AppArmor policy.

Edge Presence and signed session-intent polling are optional and disabled by default. To publish the Agent in a separately deployed Edge directory, set all four REMOTEDESK_EDGE_API_URL, REMOTEDESK_EDGE_PRESENCE_TOKEN, REMOTEDESK_EDGE_REGION, and REMOTEDESK_EDGE_GATEWAY_ID values in agent.env. The public API URL must use HTTPS; loopback HTTP is accepted only for local testing. The token must be a dedicated Presence token of at least 32 bytes, not the Edge administrator token or relay ticket secret. Restart the service and inspect sudo remotedesk-agentd status --json; graceful service shutdown removes the connection-bound registration. While online, the Agent signs each poll/ack with its device key and accepts an intent only after verifying its Client signature, local pairing grant, permission, and allowed user. Accepted terminal/file requests use an Agent-only one-use ticket to open an outbound relay tunnel to the local TLS listener. Accepted desktop requests receive session-bound TURN credentials and bind the sender to the authorized Linux user and Client fingerprint. The shared Rust str0m boundary owns bounded SDP/ICE, DataChannel, H.264 RTP, and Opus events; the existing async Agent socket driver is being migrated to that boundary. Native DEB/RPM builds use GStreamer hardware encoders when available; the static musl package excludes this dynamically linked media feature. Windows remote H.264 RTP consumption and native D3D11 presentation are wired in source, but remain disabled as a runtime capability until rebuilt and validated; this is not an RDP relay.

On the Windows controller, configure the same public origin under Global Settings > Edge session authorization. For first pairing, enter both device_public_key and tls_certificate_sha256 printed by the Agent's local pairing-code command. While that local pairing window is valid, the Client submits a signed pairing intent and completes Agent-key verification, pinned TLS/WSS, Client challenge authentication, and the eight-digit code inside the opaque relay; the code is never sent to the Edge API. The certificate-bound Agent public key is then stored in Windows Credential Manager, and subsequent terminal/file requests submit directly to Edge without a Client-to-Agent connection. Direct pairing remains a fallback when Edge or the public key is not configured. No Edge administrator or Presence token is stored on Windows.

The Windows Linux Terminal panel reports whether this mapping exists and can explicitly forget it. Its Credential Manager target is RemoteDesk/Linux/agent/<certificate-sha256>. The public key is not secret, but it is integrity-sensitive; deleting or changing it requires a new Edge or direct pairing.

Current release boundary: authenticated terminal/file transports, optional Edge Presence, signed remote first-pairing admission, known-device outbound-only rendezvous, TLS-over-relay session bytes, signed SDP/ICE forwarding, Agent/Client PeerConnection wiring, authenticated direct-WSS SDP/ICE signaling, Linux X11-to-H.264-track wiring, Windows bounded H.264 RTP-to-D3D11 presentation, and the Wayland Portal/PipeWire/EIS source path are implemented in source. Direct signaling binds the authenticated Client fingerprint, Linux user, dimensions, frame rate, and the negotiated Opus-audio flag; it enters the desktop protocol only after the PeerConnection and both ICE-end barriers complete. Wayland requires one selected monitor, strict DMABUF-to-VA negotiation, an IDR before open, and matching EIS region/input devices; failures release input and close the Portal session without software raw-frame fallback. Protocol minor 14 adds explicitly negotiated Linux output-monitor capture, bounded GStreamer Opus packets, WebRTC SRTP transport, and Windows WASAPI playback in source. Minor 13 and older clients default the audio flag to false and never receive Opus events. The new media paths, including audio, resume, and direct signaling, have not been compiled or validated end to end and are never advertised as available merely from package metadata.