MATHIAS//PETERSEN
← Project index

Distributed node runtime / 2024 to present

Orion

Why it matters A delivered remote command only proves the network accepted it, not that a device reached the requested state.

Orion explores a specific distributed-systems problem: how several edge computers can converge on the same intended software state without treating every change as an unrelated remote command.

Explore repository
StatusExperimental open source
Role in the architectureMulti-device control research / not in HeliOS
My roleFounder & Lead Engineer
DisciplinesSystems + tools / Infrastructure
01 / The work
Challenge

A successful network call proves delivery, not operation.

Once work spans several devices, configuration, streamed data, persistence, authorization, readiness, and provider failures need one model of what should happen and what actually happened.

Approach

I made desired state, observed state, and revision history the shared vocabulary.

The daemon, client, and CLI use the same typed mutations; reconciliation delegates concrete work to local providers; and control traffic stays separate from high-throughput data exchange.

02 / Architecture model Desired-state control loop

A successful request is not the end state.

Operators declare what should be true. The runtime authorizes the mutation, persists desired state, reconciles providers, observes what actually happened, and feeds that evidence back into the next plan.

InputIntent

CLI · client SDK · operator

01Control boundary

Typed requests · authentication · revision checks

02Desired state

Canonical mutations · snapshots · persistence

03Reconcile plan

Compare intent with latest observation

04Provider

Execute concrete workload or peer operations

System outputConverged state

Provider result + health + audit

Transport edgeShared domain, different traffic
  • HTTP / IPC control
  • TCP / QUIC data
  • Common auth + protocol types
03 / Implementation

The decisions beneath the summary.

01

Desired state over remote commands

Record what should be true, then reconcile it against what providers actually report.

The control plane owns typed mutations, IDs, protocol versions, canonical revisions, persisted snapshots, and observations. A successful network response records accepted intent; the runtime still has to compare desired and observed state, plan concrete work, and report whether the node converged.

  • The daemon, Rust client, and orionctl use the same public request and state contracts
  • Revision checks and shared errors make stale or incompatible mutations explicit
  • Providers and executors remain local boundaries for concrete workload behavior
02

Control and data planes

Do not force operator requests and streamed peer data through one transport model.

IPC and HTTP can serve local or remote control, while TCP and QUIC serve data-plane exchange. Transport adapters own listeners, codecs, TLS, and connection behavior at the edge. Authorization, desired state, revision semantics, and provider execution remain common regardless of how a request arrived.

  • Feature gates let an embedded host exclude network or transport surfaces it does not need
  • Local IPC provides a first-class operator path without routing through an external network
  • Peer synchronization uses the same versioned state vocabulary rather than defining a second domain model
03

Reconcile and persistence boundaries

Keep state decisions separate from the code that talks to a concrete provider.

Persistence stores desired revisions and operational records; the reconcile layer compares them with observations and produces a plan; providers and executors perform target-specific actions. This lets alternative providers and storage choices change without teaching transport handlers how to manage workloads.

  • Observations feed subsequent reconcile decisions rather than being treated as log-only output
  • Fallible typed configuration rejects invalid combinations before the daemon accepts work
  • Bounded persistence and audit queues make overload behavior an explicit operational choice
04

Operator and embedding experience

Treat readiness, audit, observability, packaging, and shutdown as part of the runtime contract.

The node daemon composes authentication, transports, persistence, reconcile work, metrics, and lifecycle behavior. Health and readiness remain distinct, audit records attach to accepted mutation boundaries, structured failure classes reach clients, and release checks validate package contents rather than only a workspace checkout.

  • Prometheus metrics, event snapshots, and transport or reconcile counters expose system state
  • Docker cluster, soak, and performance suites remain separate from fast workspace tests
  • Tarball verification checks the consumable package surface an embedding host receives
04 / Tradeoffs + limits

What this work does not claim.

01

Orion is architectural research and is not presented as a dependency shipped in HeliOS.

02

Multiple transports and provider combinations increase conformance surface even when their state model is shared.

03

Performance guardrails catch regressions in documented synthetic scenarios; they do not demonstrate production scale or an availability SLA.

05 / Engineering review

Architecture, evidence, and limits.

Explore repository ↗

Architecture

  1. 01
    Desired state instead of one-off commands

    a node can compare what should run with what it currently observes

  2. 02
    Control plane separated from data plane

    configuration and status do not inherit the throughput assumptions of streamed data

  3. 03
    Transports kept at the boundary

    IPC, HTTP, TCP, and QUIC adapt shared contracts instead of defining separate system models

  4. 04
    Operational state in the protocol

    readiness, failures, audit events, persistence, and peer synchronization are inspectable rather than log-only

Validation

  1. 01

    Health and readiness are tested as different states, while snapshots and transport counters expose where progress stopped

  2. 02

    Containerized suites exercise normal clusters, failures, adversarial inputs, and scale separately from the fast workspace tests

  3. 03

    Release checks cover typed environment configuration, public API compatibility, transport security, concurrency assumptions, and the packaged artifact

06 / Project consequence

Why it matters in practice.

  • 01Observations feed the next reconciliation decision, so command delivery is not mistaken for completed work
  • 02Local CLI and remote control paths apply the same revision and authorization rules
  • 03Feature-gated transports let an embedded host exclude network surfaces it does not use
  • 04Readiness, bounded queues, and structured failures make degraded operation visible to clients
My ownership
  • Runtime architecture
  • Client SDK
  • Operator CLI
  • Auth, audit, and observability
Built with
  • Rust
  • SDKs
  • CLI
  • Observability
  • Authentication