Mercurius is designed around a small, composable set of ideas.
Mercurius’s design is a message‑passing system where every component acts locally and routing emerges from uniform rules.
Design
Core Concepts
Mercurius is designed around a small, composable set of ideas:
- A stable, long‑lived workstation acts as the authoritative environment.
- Portals connect to this workstation using a protocol designed for presence, not display.
- State lives on the workstation; interaction happens wherever you are.
- The protocol is optimised for SCTP and efficient over modern networks.
- The system must be secure against DDoS and APT attacks.
The design is intentionally minimal. Complexity belongs in the workstation, not in the protocol.
Mercurius rests on one load-bearing idea: its components are independent Objects which collaborate by constructing and passing Messages. Each Object handles the part for which it has responsibility and authority, then consumes the Message or hands it onwards. The sender need not discover the eventual receiver, know where it lives, or know whether the Message crosses a process or network boundary. Behaviour emerges at run time from the cooperation of the whole object community rather than from one procedure which directs the system. There is no global Message Router with knowledge of every destination, and no central authorisation ladder asking whether this user may access that Window. Delivery and authority emerge as each Object makes a bounded local decision using only its own relationships and responsibilities.
Even main() is not a god Object. It is the composition and
lifetime root: it creates a small number of top-level Objects, starts them,
waits for shutdown, and destroys what it owns. A Controller then waits for
Messages from its Transport. When a Message arrives it performs its bounded
part of the collaboration; when none arrives it has no protocol work to do.
There is no central tick which walks the object graph and tells the system
how to behave.
Security Model
Mercurius is designed for a zero-trust network: establishing a connection establishes communication, not authority. A Portal gains no privilege merely from its network location, from running locally, or from knowing identifiers for Sessions, Windows, Seats, or other resources.
The Security Model describes the three independent gates through which trust is established: the Portal authenticates the Workstation, the Workstation authenticates the user, and the Workstation authorises each action within its Session. It also explains how Mercurius protects long-lived Sessions after login, keeps authority scoped to the authenticated user and Session, and treats every Portal and network as untrusted.
Security is therefore not a wrapper around the protocol or a property supplied by a VPN. It is expressed in the protocol, the Session model, Object ownership, Message routing, and the explicit boundaries through which authority may pass.
Four elevations of design
Mercurius separates four related questions which are easily confused. The RFC defines behaviour visible between implementations. The architecture describes the concrete Mercurius Objects and how they are assembled. The software-design paper describes the general discipline those Objects follow. The C Coding Standards define how that discipline is expressed mechanically in source code.
Smalltalk-Style Software Design in C
Smalltalk-Style Software Design in C presents a discipline for designing systems as communities of cooperating Objects. It covers Message passing, bounded responsibility and authority, explicit ownership and lifetime, Design by Contract, and the four Iron Rules.
The paper is useful beyond Mercurius. Mercurius is its substantial worked example: Controller, Broker, Session, Application, Compositor, Presenter, and Projector cooperate through narrow interfaces without collapsing into a procedural call graph.
Read Smalltalk-Style Software Design in C.
Mercurius Architecture
The Architecture is the elevation of the Mercurius reference implementation: its concrete Objects, their ownership and relationships, and the way they are assembled into a running system.
Unlike the other elevations, the Architecture is meaningful only alongside the implementation it describes. It is therefore maintained with the Mercurius source code rather than published on this website, so that the architectural drawing and the code can be read and updated together.
C Coding Standards
The design paper describes the structural discipline; the C Coding Standards describe its mechanical expression in Mercurius. They cover naming, method shape, ownership checks, error handling, documentation, and safe use of C.
Development Methodology: Milestones, Waypoints and Rabbits
Mercurius is developed using a methodology called Milestones, Waypoints and Rabbits (MWR), an approach to refining requirements and making an otherwise unbounded problem tractable.
The design elevations describe what Mercurius is and how it is constructed; MWR describes how work is selected while that design is realised. Milestones define observable capabilities. Work required for the current Milestone is recorded as Waypoints; other work worth retaining is recorded as Rabbits. The Methodology page describes this trail-driven approach in full.
Design Constraints
Why SCTP‑only is the right choice for Mercurius
The protocol’s guarantees depend on SCTP semantics, and plain TCP cannot provide these without re‑implementing SCTP in user space. If TCP becomes a first‑class transport, implementers will choose it because it is easier.
This leads to:
- Degraded latency
- Broken prioritisation
- Unpredictable input timing
- A “remote desktop” feel
- The protocol being judged by its worst transport
Mercurius avoids this by depending on SCTP’s modern transport semantics:
- Independent ordered streams
- Message boundaries
- Partial reliability
- No cross‑stream head‑of‑line blocking
- Multi‑homing and stable associations
These are the foundation of:
- Deterministic compositor behaviour
- Responsive input under load
- High‑motion video surfaces
- Relocatable sessions
- Multi‑seat concurrency
Why Vulkan‑only is the right choice for Mercurius
Mercurius requires Vulkan for the same reason it requires SCTP: the system depends on properties that only Vulkan provides natively. The compositor, the Session model, and the rendering pipeline all assume explicit GPU control, predictable synchronisation, and cross‑platform consistency.
Allowing multiple GPU APIs would force the compositor to:
- support multiple backends with incompatible semantics
- fall back to lowest‑common‑denominator rendering
- lose deterministic behaviour due to implicit driver state
- abandon multi‑GPU awareness and migration
- be judged by its weakest renderer
Vulkan provides the architectural guarantees Mercurius depends on:
- Explicit resource ownership — no hidden allocations or global state.
- Deterministic command submission — the compositor knows exactly when work is queued and completed.
- Cross‑platform consistency — Vulkan is the only modern, vendor‑neutral GPU API.
- Zero‑copy surface handling — structured and video surfaces rely on explicit memory control.
- Multi‑GPU enumeration — Sessions can migrate between GPUs because Vulkan exposes devices explicitly.
Software compositing is insufficient: Mercurius is designed for high‑motion video surfaces, GPU‑accelerated compositing, and multi‑session concurrency. A workstation without a Vulkan‑capable GPU is simply not a Mercurius workstation.
Why DANE is the right choice for Mercurius
Mercurius is designed primarily for workstations within an organisation's network and administrative domain. The organisation already controls the names of those workstations through DNS, so DNSSEC provides a natural trust anchor for establishing their cryptographic identity.
DANE (DNS-based Authentication of Named Entities) uses DNSSEC-protected TLSA records to associate that identity with the workstation's DNS name. This allows Mercurius to authenticate a workstation without depending on a public Certificate Authority or requiring the organisation to maintain a separate private CA solely for Mercurius.
This has some useful properties:
- Local authority — the organisation that assigns the workstation's DNS name also controls the information used to authenticate it.
- Scoped trust — trust follows the DNS hierarchy rather than a separately distributed collection of trusted certificates.
- No public CA dependency — internal workstations do not need certificates issued through the public Web PKI.
- No separate Mercurius PKI — organisations do not need to establish and distribute another root of trust simply to deploy Mercurius.
- DNS-based lifecycle — changes to workstation identity can be managed through DNSSEC and TLSA records alongside the names they describe.
For example, a Portal connecting to
server04.bigcorp.comcan:
-
query and validate the DNSSEC-protected TLSA record for
server04.bigcorp.com; - verify the workstation's cryptographic identity against that record;
- establish an SCTP association protected by DTLS; and
- authenticate the user over the resulting secure connection.
The workstation and the user are therefore authenticated separately. DANE establishes that the Portal has reached the workstation named by the organisation; Mercurius authentication establishes who is asking to use it.
For Mercurius, this keeps workstation trust within the same administrative hierarchy that already names and operates the workstations, without introducing another trust infrastructure simply for the window system.