Skip to content

Architecture Overview

Detent separates three jobs that most configuration systems blur together: deciding what the configuration is, distributing it, and serving it to code. Each runs at a different speed and fails differently, and keeping them apart is what lets a read stay a few hundred nanoseconds while distribution can be down for an hour.


Producers write transactions to the authority; the optional relay subscribes to it and serves snapshots and deltas to each host's agent, which publishes immutable generations that the app process and detent get map and readProducers write transactions to the authority; the optional relay subscribes to it and serves snapshots and deltas to each host's agent, which publishes immutable generations that the app process and detent get map and read

This is the managed profile, the topology Detent’s production contract targets.


ActorWhat it doesRuns onBinary
ProducerWrites knob changes as namespaced transactionsAnywhere that reaches the authorityYour service, or curl
AuthorityOrders, stores and serves the source of truthThree machines, one voter eachdetent-authority --authority authority.json
RelayOptional fan-out: one upstream subscription per bundle, many agentsBetween the authority and agent hostsdetent-relay
AgentReceives snapshots and deltas, publishes immutable generationsEvery application hostdetent-agent --managed managed.json
ClientMaps the selected generation and reads in memoryEvery application hostYour app (detent::Client), detent get

Voters, relays and agents are all daemons; “daemon” names no role. Each actor has its own page: Authority, Relay, Agent and Delivery and Local Images for the agent’s generations, and Read Path for the client. Detent’s actors in the repository is the full reference: endpoints, files, build options, default directories and restart behavior for every actor.


The read path runs inside your process and does nothing but memory access: validate the name, check the CLI override table, load the current snapshot pointer, look up the knob, and evaluate it. No network, disk, lock or allocation. See Read Path.

Update Plane: the Client’s Background Thread

Section titled “Update Plane: the Client’s Background Thread”

One background thread per client picks up new state from its source. With managed delivery, it watches the agent’s selected descriptor and maps each new generation. With a file source, it fetches candidates, validates them completely, gates them by version, merges them over the baked defaults, and publishes the result with one atomic store. Failures never reach readers. See Update Path.

The authority accepts transactions and replicates them durably across its voters; relays and agents carry the committed state to every host as snapshots and deltas. See Authority and Relay.


  1. Reads never wait on distribution. A distribution failure degrades freshness, never availability.
  2. Immutable snapshots, atomic swaps. Readers see one complete, validated configuration or the previous one, never a mixture.
  3. Fail fast on programmer errors. A missing knob is a bug, so it’s loud; an unreachable source is an outage, so it’s quiet and observable.
  4. Whole-definition replacement. A knob is an atomic unit; there’s no field-level merge to reason about.
  5. Everything is bounded. Request bodies, snapshot sizes, queues, history, retained memory and disk are all limited before allocation.
  6. Measured, not asserted. Performance claims come with a reproducible benchmark and its caveats.

  1. Read Path and Update Path: the client.
  2. Agent: host-local reads.
  3. Durable Authority: transactions and durable consensus.
  4. Relay: optional durable fan-out.
  5. Delivery and Local Images: managed distribution and immutable generations.
  6. Dependencies: the libraries Detent is built from.
  7. Design Documents: the full engineering record in the repository.