Skip to content

Configuration

Every Detent setting has a built-in default, so nothing needs configuring for a local setup. This page collects every file, directory and environment variable.


command-line flag > environment variable > configuration file > built-in default

User configuration takes precedence over system configuration; --config PATH selects a file explicitly. Relative paths inside a configuration file are resolved against the file’s own directory. Unknown fields are rejected.


PlatformUserSystem (--system)
Linux$XDG_CONFIG_HOME/detent, else ~/.config/detent/etc/detent
FreeBSD$XDG_CONFIG_HOME/detent, else ~/.config/detent/usr/local/etc/detent
macOS~/Library/Application Support/Detent/Library/Application Support/Detent
PlatformUserSystem
Linux$XDG_STATE_HOME/detent, else ~/.local/state/detent/var/lib/detent
FreeBSD$XDG_STATE_HOME/detent, else ~/.local/state/detent/var/db/detent
macOS~/Library/Application Support/Detent/state/var/db/detent
PlatformUserSystem
All$XDG_RUNTIME_DIR/detent, else $TMPDIR/detent-<uid> (mode 0700)Linux /run/detent, BSD/macOS /var/run/detent
PlatformSystem
Linux/var/lib/detent-agent
FreeBSD, macOS/var/db/detent-agent

On macOS, an absolute XDG_* variable overrides the native location too.


{
"managed_path": "managed.json",
"generation_dir": "agent-state",
"defaults_path": "defaults.json",
"runtime_dir": "/run/detent",
"log_level": "info",
"verbosity": 0,
"color": "auto"
}
FieldMeaning
defaults_pathOptional fallback knobs; defaults.json beside the config is found automatically
runtime_dirRuntime directory
managed_pathPrivate managed credential file
generation_dirManaged generation directory
log_level, verbosity, colorLogging

An explicitly configured defaults file must exist and be valid; an absent conventional defaults.json is skipped.

FieldDefaultMeaning
port8317HTTP port
authoritynoneThe authority configuration file detent-authority serves
reactors4Network reactor threads
runtime_dirruntime directoryPID and log files
log_level, verbosity, colorLogging

The managed agent’s private credential file. See Managed Delivery for every field and its resource bounds.

compaction_interval_ms defaults to 60,000. Zero disables periodic compaction; enabled values range from 1,000 to 86,400,000. Checks run between upstream exchanges, and admission pressure skips an optional attempt. Reader leases and durable collection determine when old storage can be reclaimed.

The authority’s private configuration. See Operations: Durable Authority.


The private authority configuration accepts an optional subscription_limits object. Unknown fields are rejected. Session controls use separate admission from publishers.

FieldDefaultMaximum
sessions1,02465,536
per_principal25665,536
idle_ms60,00086,400,000
maximum_ms600,00086,400,000
opens16128
polls256512
closes16128
per_principal_controls865,536
per_principal_polls25665,536
open_bytes262,1441,048,576
control_bytes4,09616,384
wait_ms30,00060,000

Counts and byte bounds must be positive. wait_ms may be zero. Maximum lifetime must cover idle lifetime. Actual storage admission also depends on the delivery ledger; raising logical limits does not reserve unlimited memory.

application_limits.layout sets the history layout policy that the enabling entry proposes. It is validated the same way as an administrative layout change. The consensus log limits always come from consensus_limits.

FieldDefaultMeaning
seal_transactions2,048Positioned changes per seal
seal_bytes8,388,608Positioned bytes per seal
period64Seals between a namespace’s roll-ups
carry_bytes, carry_count4,096 and 2A roll-up this small stays a section
ratio4Squash ratio between adjacent blocks
alpha_num, alpha_den1 and 8The block limit, as a fraction of a namespace’s live bytes
cap2Disk cap, in units of the block limit

The private managed agent configuration names the followed namespaces (every granted namespace when absent) and follows them over one W5 session; the server negotiates long-poll duration. Failed exchanges use exponential reconnect backoff with equal jitter, starting at retry_interval_ms (default 200) and capped by reconnect_maximum_ms (default 30,000, or the retry interval when larger). The cap must cover the retry interval and cannot exceed 86,400,000 ms. Each coordinator seeds its schedule independently; authenticated idle responses and durable publication reset backoff. Successful long polls and disk completion waits are unchanged.


VariableUsed byMeaning
DETENT_MANAGED_CONFIGagent, detentPrivate managed configuration
DETENT_GENERATION_DIRagent, detentDurable generation directory
DETENT_DEFAULTS_PATHdetentDefaults file
DETENT_RUNTIME_DIRagent, detentRuntime directory
DETENT_AUTHORITY_PORTdetent-authorityPort
DETENT_AUTHORITY_REACTORSdetent-authorityReactor threads
NO_COLORdaemonsDisable automatic color
XDG_CONFIG_HOME, XDG_STATE_HOME, XDG_RUNTIME_DIR, TMPDIRallBase directories

FileOwnerMode
agent.json, detent-authority.jsonrootreadable by the service account
managed.json, authority.jsonroot or service account0600, or controlled 0640
Authority stateservice account0700
System agent runtime directoryservice account0755, with 0644 pid and snapshot
Managed generation artifactsservice account0644 by default for system agents

Private configuration must be a regular, single-link file without world access or group/other write permission; Detent refuses it otherwise.

The private relay host configuration accepts connections (default 1,024) and service_limits with the requests in flight per lane: opens (16; the history routes share it), polls (640) and closes (16), each 1 to 65,536. See the relay guide for the heap budget and a complete example.

A relay configuration requires a mirror object: the relay mirrors namespace history from the authority’s voters, or from another relay, and serves it to version 2 sessions and to downstream relays. Each of its credentials grants namespaces patterns.

FieldDefaultMeaning
directoryrequiredThe mirror’s own directory, mode 0700
clusterrequiredThe authority’s cluster identity, 32 hex digits
namespacesrequiredThe names mirrored, in increasing order, at most 4,096
upstreamsrequiredUp to 64 {"address", "port"} objects, read in turn: a failure, or an answer older than the mirror, moves to the next
tokenrequiredThe relay’s credential at its upstream
hostname, calocalhost, the relay’s caHow the relay verifies its upstream
interval_ms250Time between syncs, 1 to 60,000; a failed sync doubles it, up to reconnect_maximum_ms
reconnect_maximum_ms30,000, or the interval when largerThe longest wait after failed syncs, from the interval to 86,400,000
timeout_ms10,000Deadline for each upstream request
compressionfalseRead W6 answers in zstd
sessions1,024Sessions the relay holds
answer_bytes67,108,864Memory for answers in flight, 1 MiB to 4 GiB

A managed source can set authority_endpoints to an array of up to eight objects such as [{"address":"127.0.0.1","port":8317},{"address":"127.0.0.2","port":8317}], replacing the top-level address and port. Destinations must be distinct IP addresses with nonzero ports. All entries share the configured TLS hostname, CA, credential, authority identity and namespace scope.

The coordinator tries members serially and stays on a successful member. Transport failures, unavailable authorities and follower read rejection permit rotation. Admission pressure and local storage failures retain the route. Authentication, authorization, TLS verification and unexpected identity or profile fail closed, including denials received while closing a session. Sessions and publication feedback remain bound to their opening endpoint.

For pooled subscriptions, quorum_refresh_ms defaults to 30000 and accepts 1000 through 86400000. Refresh uses bounded jitter of ±20%; idle responses do not postpone it. A fresh Open revalidates authority quorum after accepted local publication and recovery settle. Polling already performs quorum reads. Discovery time includes refresh, per-member request deadlines, retry backoff and accepted local work; the default 60-second request timeout provides no short failover guarantee.

Pools contain authority endpoints. Relay Open does not establish current authority quorum. An agent consuming a relay must use a single relay endpoint and explicit "delivery_mode":"subscription".