Last updated: September 25, 2026

Architecture

Three binaries and one protocol. Authority is split on purpose: the control plane decides what should run, each host decides what will run on it, and neither can rewrite the other's record.

How is Decentralized.Host built?

Decentralized.Host has three binaries: dh-control (a Raft control-plane member that signs desired state), dh-noded (a sovereign host agent that admits, runs, observes and journals work) and dh (the operator CLI). Hosts talk to each other over userspace WireGuard with SWIM gossip.

Source: docs/architecture.md
attenuated capability · TLS
signed bundles · stateIndex
signed observations back to the control plane

Select a block for what it holds and does.

Control plane

dh-control · runs on 1, 3 or 5 machines
Holds
  • Raft log and snapshots (bbolt)
  • member identity and root-issued certificate
  • artifact CAS
  • optional Postgres mirror (never the source of truth)
Does
  • ›Replicates desired state through Raft over mutual TLS; the state machine is deterministic and holds the audit ledger.
  • ›Only the verified leader issues bundles, signs assignments and reconciles; every bundle carries a state index so hosts refuse rollback.
  • ›Scheduler plans placements deterministically; the reconciler turns plans into signed assignments with per-assignment capabilities and rolling updates.
  • ›Verifies host observations (host key, monotonic seq) and projects views where every value carries a truth basis.
  • ›Serves the operator console (no build step, CSP default-src 'self').
source: pkg/control, cmd/dh-control

The path of a deployment

  1. 01 · dh → control plane
    Apply

    A dh/v1 manifest is validated strictly (unknown fields rejected), normalized, hashed and committed through Raft as desired state.

  2. 02 · control plane
    Plan

    The deterministic scheduler filters hosts by tier, resources, architecture, features, anti-affinity and failure domain. `dh explain app` shows the plan.

  3. 03 · control plane (leader)
    Sign

    The reconciler issues signed assignments, each with a capability bound to one host, generation, artifact digest and resource ceiling.

  4. 04 · host
    Admit

    The host checks the pinned root, roster, signature, audience, generation, clock, capability chain, revocation, freeze, freshness and its own policy — 18 checks, in order.

  5. 05 · host
    Run

    Artifact chunks are fetched from peers and BLAKE3-verified; the admitted generation starts under the process or docker runtime.

  6. 06 · host → control plane
    Observe

    The host signs what it measured. Nothing is shown as running until a host has observed it; desired, admitted and observed stay separate.

  7. 07 · edge
    Route

    Edge hosts probe replicas over the mesh and route only to healthy ones.

  8. 08 · anyone with the ledger
    Verify

    `dh audit verify` checks the hash chain and signed checkpoints locally; hosts keep their own ledgers too.

Wire and storage formats

Everything signed or hashed uses canonical JSON: integers only, sorted keys, and duplicate keys, lone surrogates and invalid UTF-8 rejected. Envelopes are Ed25519 signatures over a domain-separated context plus the canonical payload. Identifiers are dh1… derived from public keys. The protocol is specified in docs/protocol/dh-v1.md and pinned by 136 conformance vectors.

Where it differs from a typical orchestrator

  • › The control plane proposes; hosts admit or refuse under local policy.
  • › Losing the control plane holds work in place instead of stopping it.
  • › Nothing is reported as running until a host signs that it observed it.
  • › Workloads are reached through per-assignment mesh forwarders, not routed per-workload IPs.
  • › Postgres, if configured, only mirrors evidence; Raft is the source of truth.

Architecture decision records