Skip to content

Basic Concepts

There are a few concepts that are core to Detent. Understanding them from the outset will make everything else much easier to follow.


A knob is a single named configuration value that a running process reads. Every knob holds one signed 64-bit integer: 0 or 1 for a feature flag or kill switch, any value for a limit, a size or a timeout. Knobs never hold strings, floats or structured data; that restriction keeps evaluation trivial and the read path allocation-free.

Every knob name has exactly two parts separated by one colon:

checkout:killswitch_new_path
└──┬───┘ └────────┬────────┘
knobset local name

Both parts use letters, digits, ., _, / and -, and the whole name is at most 200 bytes. The left part groups related knobs, usually by service or team. See Knobs and Names for the exact rules.

A definition describes how to evaluate a knob: a default plus two optional refinements, per-group overrides and a rollout percentage. A percentage comes with a rollout_value, the value callers inside it get.

{ "default": 25 }
{ "default": 0, "overrides": { "employees": 1, "beta": { "rollout_pct": 50 } },
"rollout_pct": 10, "rollout_value": 1 }

A definition is atomic. Publishing a knob always replaces its whole definition; there is no field-by-field merge.

A snapshot is a complete, immutable, validated map from knob names to definitions, stamped with a version number. Readers always see exactly one snapshot at a time. The background updater builds a brand-new snapshot for every accepted update and publishes it with a single atomic pointer swap, so no reader ever observes a half-applied change.

Every published snapshot carries a positive integer version. A client only accepts a version greater than the one it already has, so reordered, repeated or replayed updates are harmless: they are counted as stale and ignored.

Baked defaults are a snapshot file shipped with your binary, conventionally named defaults.json. They are loaded at startup as version 0, before any live data arrives, and they remain the fallback for any knob that the live snapshot doesn’t mention. They are also where new knob names are introduced.

A source is where live snapshots come from. A client consumes exactly one source: nothing (baked defaults only), a local file that it polls, or an HTTP endpoint that serves GET /v1/snapshot. The managed agent adds a fourth, durable immutable generations delivered from an authenticated authority.

The durable authority, detent-authority --authority, is the server that publishers write to. It authenticates each publisher, applies atomic, per-namespace transactions, commits them through durable Raft consensus, and delivers the result to managed agents.

The agent, detent-agent, is a host-local daemon that receives authenticated deliveries from the authority and publishes immutable generations on disk. Shell scripts and programs in any language read knobs from them with detent get without talking to the network or to the daemon.

There are two kinds of override, and they are easy to confuse:

  1. Group overrides live in a knob’s definition and apply when the caller passes a matching group, the switch_val. They are published like any other part of a definition.
  2. CLI overrides are name=value pairs given to one process at startup. They shadow both the baked defaults and every live snapshot for that process only, which makes them ideal for local debugging and tests.