Skip to content

Shell Scripts and the Agent

Not every process that needs a knob is a long-running C++ service. Cron jobs, deploy scripts, health checks and programs in other languages can read knobs through detent, the shell reader, backed by detent-agent, one small daemon per host.


detent-agent receives deliveries from the authority once for the whole host and publishes immutable generations on disk; every detent get maps the selected generation read-onlydetent-agent receives deliveries from the authority once for the whole host and publishes immutable generations on disk; every detent get maps the selected generation read-only

The agent receives snapshots and deltas over verified TLS, builds a new immutable image for each, and selects it atomically. detent get maps the selected image read-only and evaluates directly against it: no socket, no request to the daemon, no JSON parsing. A generation stays readable with the agent stopped.


Terminal window
detent get search:max_results
# 25
detent get payments:new_processor --hash user-42
# 1
detent get payments:new_processor --hash user-2 --switch employees
# 1

With --managed PRIVATE_CONFIG (or managed_path in agent.json), the first get starts the agent if no generation is present and waits for the first one. With neither --managed nor --generation-dir configured, get fails with no source configured; --default doesn’t mask that.

Exit statusMeaning
0The value was printed to stdout as a decimal integer
1The knob couldn’t be read; the reason is printed, e.g. ERR MissingKnob: checkout:nope (not present in current snapshot)

For scripts that must keep going, --default supplies a fallback for that one read:

Terminal window
if [ "$(detent get checkout:new_path --default 0)" = 1 ]; then
run_new_path
fi

Write agent.json in your config directory:

PlatformUser config directory
Linux, FreeBSD$XDG_CONFIG_HOME/detent, otherwise ~/.config/detent
macOS~/Library/Application Support/Detent
agent.json
{
"managed_path": "managed.json",
"generation_dir": "agent-state"
}

Then plain detent get NAME works from any directory. You can also pass --managed PATH and --generation-dir PATH, or set DETENT_MANAGED_CONFIG and DETENT_GENERATION_DIR; flags override environment variables, which override the config file. Managed Delivery covers managed.json.

An optional defaults.json next to agent.json gives detent get fallback knobs while no generation has arrived, and for knobs a generation doesn’t contain:

Terminal window
detent get search:max_results --defaults ./defaults.json

Terminal window
detent-agent --status --managed managed.json
# running (pid 65214)
# durable revision=3 knob_count=2

--status never starts anything. Stop a user agent with SIGTERM:

Terminal window
kill -TERM "$(detent-agent --status --managed managed.json | awk '/^running/ {gsub(/[^0-9]/, "", $3); print $3}')"

The agent keeps its runtime files (agent.pid, agent.log) in $XDG_RUNTIME_DIR/detent, or a private detent-<uid> directory under the system temporary directory, created with mode 0700. Use the same --runtime-dir for get and --status if you override it.

On servers, run the agent under the service manager instead; see System Services. System readers use --system, which attaches to the managed agent and never starts a private one:

Terminal window
detent get search:max_results --system