# How QuickDesk works

> This page explains the QUIC connect-by-slug transport, the parked-stream relay, and the end-to-end encryption model of a QuickDesk session.

A QuickDesk session is a **1:1 control loop**. The session runs over the same
raw-QUIC relay that carries HTTP and TCP tunnels. The design goal is a session
with no listening port on either machine. The session must still traverse NATs
and survive network changes.

## Why raw QUIC, not pub/sub

Remote desktop is a low-latency **request/response loop** between exactly two
peers. Input events go one way. Framebuffer and audio go the other way. A
single ordered QUIC stream models that loop cleanly and keeps the relay out of
the trust path. A publish/subscribe fabric is the correct tool for one-to-many
media. But it would force every session through a broker and add fan-out
semantics that this loop does not need. So QuickDesk uses a **raw QUIC
stream** for the control loop.

## Connect-by-slug over the parked-stream pool

A QUIC server cannot open a stream toward a client. Only the client opens
streams. So the controlled box pre-opens a small pool of bidirectional streams
and **parks** them idle. When a controller connects, the edge pops a parked
stream and splices the two streams together.

  1. **The box registers its device id**
On launch, the controlled box dials the edge over QUIC. It registers its
    **device id as a slug** (`"proto":"quick"`). It then pre-opens and parks a
    few bidirectional work streams. The HTTP/TCP tunnels use the same
    registration. The device id *is* the slug.
  2. **The controller dials by id**
The controller enters the box's device id. The edge looks up the slug.
    The edge then pops an idle parked stream from that box's pool and writes
    a small `connect` metadata frame onto it.
  3. **The edge splices**
The edge becomes a transparent byte relay between the controller's QUIC
    stream and the box's parked stream. From this point, the edge moves bytes
    and cannot interpret them.
  4. **The clients handshake end to end**
Over that byte pipe, the two clients run QuickDesk's own signed key
    exchange. The clients then exchange input, framebuffer, and file-transfer
    messages under end-to-end authenticated encryption. The relay carries
    only ciphertext.

> **NOTE:**
> The device id is also the connect address. There is no separate rendezvous
> step and no inbound port. Both peers are QUIC **clients** that dial out. The
> edge brokers them by slug.

## Control plane vs data plane

| Plane | Transport | What it carries |
| --- | --- | --- |
| **Control plane** | HTTPS + JSON | login / SSO, device registry, address book, audit and recording upload, session tokens. No pixels. |
| **Data plane** | raw QUIC (connect-by-slug) | the encrypted desktop session — input, framebuffer, audio, file transfer. |

## Why the relay stays untrusted

Transport TLS secures only the **hop** from each client to its edge PoP. The
edge terminates that TLS to route bytes. If the session relied only on
transport TLS, the edge *could* see plaintext. The session does not rely on
it. QuickDesk keeps a second, independent layer:

- A **public-key handshake** authenticates the two peers to each other and
  derives a session key. The relay never learns this key.
- The clients seal all session messages with **authenticated encryption**
  under that key, end to end.

A compromised or hostile relay can drop or delay a session. It cannot read or
forge the session contents. For this reason, QuickDesk can run over a shared
managed relay and still make an end-to-end confidentiality claim.

## Resilience & reach

- **No head-of-line blocking.** Each session uses its own QUIC stream. One
  slow session never stalls another session on the same box or edge.
- **Survives network flaps.** QUIC connection migration lets a client move
  networks (Wi-Fi → cellular). The session stays up.
- **Multi-region by mesh.** A box connects to its nearest PoP. When a
  controller lands on a different PoP, the edge↔edge mesh routes it to the
  box's PoP. A device is reachable by id from anywhere.

## On the edge fast path

The relay handles session bytes on a fast path, not on a general-purpose
stack:

- Each edge runs a **shard-per-core** reactor with a **kernel-bypass** NIC
  path and **io_uring** for async I/O.
- Cross-shard hand-offs use **lock-free** rings.
- The public QUIC listener uses **SO_REUSEPORT**, so each shard owns its
  accept queue.

The slug → session table changes at runtime as devices connect and
disconnect. The table is shared across the edge mesh, so any PoP can route to
the PoP that holds a given box.

## Related

- [Overview](/modalities/quickdesk/overview) — what QuickDesk is and what to build
- [Tunnel — wire model](/modalities/tunnel/details) — the shared parked-stream relay in full
- [Security & audit](/modalities/quickdesk/security) — the trust model end to end