Documentation

How a Session Works

What happens between a technician clicking Connect and controlling a machine.

Three parties. Both ends dial out.

A session connects the Agent (technician console in a browser) and the Client (the Windows machine) through the Relay you run. Both endpoints dial out to the relay over WSS, so neither needs a public IP or an inbound firewall rule; the relay matches them by session id.

How a Secure Desk session works

Session flow

  1. Create or enroll

    Sign in to the portal. Send a join link (attended, portable client) or open an enrolled device (unattended, installed service). The user opens the link and gets a one-click launcher, or types their code on your join page.

  2. Validate

    The relay validates the session id against the portal's registry — format, token, expiry, single-use — with constant-time comparisons. A one-time link is consumed once its client session ends.

  3. Pair and key

    Once both sides are present they run an ECDH exchange through the relay and derive their own AES-256-GCM keys. See the security model.

  4. Work the session

    Screen to the console; input back when Control is on. Chat, voice, clipboard and file transfer travel over the same encrypted channel.

What the relay does

The relay pairs two sockets presenting the same session id and forwards frames between them without interpreting the payload. Keeping it that way limits what it can see and keeps it out of the cardholder-data path. The one message it originates is peer state — telling each endpoint when its partner is present — so neither side encodes frames nobody is receiving.

Capture and encoding

The client captures the screen with GDI by default (it works everywhere, including from a service), with DXGI Desktop Duplication as a faster path where it initializes. Each frame is split into 128×128 tiles; only changed tiles are encoded and sent as a delta, with a full key frame periodically. The console paints tiles onto a canvas, aspect-fit to the window.

A mostly static desktop costs very little bandwidth; full-screen video costs a lot. Quality presets top out at 15 / 12 / 8 fps.

Input

Mouse and keyboard coordinates are normalized to 0–65535, so the technician's screen resolution doesn't matter.

Desktop vs backstage

Mode isn't a relay concept — the relay only pairs by session id. The desktop session and the backstage SYSTEM shell use separate, derived session ids, so the user still shares just one code.

File transfer

Either side can push a file: an open message with name and size, then 64 KB chunks respecting WebSocket backpressure, then a close carrying the SHA-256 of the whole file. The receiver verifies the hash before acknowledging. On Windows, received files land in Downloads; the console downloads what it receives. This is send/request of files, not a remote file explorer.

Portal data model

Users
Technicians, with a role of admin, operator or viewer.
Customers
Group devices, so an MSP technician works within one client at a time.
Devices
Enrolled installed clients, each with its own device token and live presence.
Sessions
One-time or reusable support sessions with expiry and live status.
Requests
Ad-hoc access requests raised from the join page, for a technician to accept.
Audit log
Last 200 portal administrative and session events (not command-level shell activity).

Known limits

  • The Windows secure desktop (UAC prompts and Ctrl+Alt+Del) is not captured. Sign-in and lock screens are.
  • Endpoints are Windows only. The technician console is cross-platform because it's a browser page.
  • The tile codec is efficient for typical desktop work, not full-motion video.

Something unclear or missing? Tell us and we'll improve this page.