Environment variable reference

This page lists Registry Stack’s supported fixed environment-variable interfaces for runtimes, adopter tooling, and installers.

The stack’s other kind of environment variable is operator-named. Secret material is not read from a fixed variable name: a configuration field carries a reference that names the variable, and the operator chooses the name. Base Registry Engine and Registry Evidence work that way, and the reference grammar is closed rather than free-form. Each reads a secret from an operator-named variable only when its runtime file opts in to the environment provider, as its section records.

Configuration expansion

Registry Evidence substitutes ${NAME}, ${NAME:-fallback}, and ${NAME:?message} in string values of its runtime file while the shared configuration reader builds the document, so a substituted value is always text: it fills a string member and never a number or boolean. A bare ${NAME} refuses the file when the variable is unset or empty, ${NAME:-fallback} substitutes the fallback in that case, and ${NAME:?message} refuses the file with a diagnostic that names NAME and withholds the message, because the message is configuration, which a diagnostic does not repeat. It refuses an expression in apiVersion and kind, in a member whose key ends in Ref or Refs, and under secretProviders, so the environment cannot choose which secret is read or where it comes from. It refuses any ${...} expression in the governed bundle, so the reviewed bundle is the one that runs, and in a verification policy, which states every expectation literally. evidence check checks an expression by its syntax and position only, unless --environment substitutes from its own environment as startup does; an expression in a number or boolean member is refused either way.

Base Registry Engine substitutes ${VAR}, ${VAR:-default}, and ${VAR:?message} in string values of its runtime file after parsing, through the shared configuration loader, and refuses any ${...} expression in the authored project or module files, as its section records.

There is no escape for a literal ${ in a runtime file that substitutes. Put the literal text in a variable and reference that variable: a substituted value is not expanded again.

Registry Evidence

evidence reads one fixed variable, EVIDENCE_LOG, and only in evidence serve.

Name	Purpose	Default or required
EVIDENCE_LOG	Tracing filter for the operational records the serving process writes as line-delimited JSON on standard error.	Defaults to info. Read by evidence serve only; offline commands install no log subscriber.

Registry Evidence reads no variable for the runtime path. Every subcommand that reads the runtime file takes it as the required --runtime-config <FILE> flag after the subcommand, for example evidence check --runtime-config /etc/registry-evidence/runtime.yaml. The global --runtime flag and the REGISTRY_EVIDENCE_RUNTIME variable are removed: evidence refuses either one at startup and names --runtime-config as the replacement, rather than silently ignoring it.

Secret references

Registry Evidence resolves secrets through the providers runtime.yaml declares under secretProviders: file: {root: <absolute directory>} enables secret:file/<name> references, which resolve to an owner-only regular file under that directory, and environment: {} enables secret:env/<NAME> references, which resolve to the operator-named environment variable.

Grammar	Resolves to	Accepted name
secret:env/<NAME>	The value of the environment variable <NAME>, when secretProviders.environment is declared	Starts with an uppercase ASCII letter, then uppercase ASCII letters, digits, or _, up to 128 characters
secret:file/<name>	A file named <name> under secretProviders.file.root	Starts with a lowercase ASCII letter, then lowercase ASCII letters, digits, ., _, or -, up to 128 characters

A reference in the runtime file or the governed bundle that names a provider the runtime file does not declare is refused at startup, so an environment-backed secret is always an explicit operator choice. See the Registry Evidence configuration reference for the runtime file and the bundle it binds.

Evidencectl

Name	Purpose	Default or required
EVIDENCE_BIN	Path to the evidence binary used by commands that delegate runtime validation or evaluation. An explicit --evidence-bin takes precedence, then this variable, then PATH lookup.	Optional.

Registry Evidence toolset installer

The Registry Evidence toolset installer stages evidence, evidencectl, and evidence-oid4vci, then verifies every binary against SHA256SUMS before anything reaches the install directory. The commands switch version together through a single toolset-pointer rename, and a failed switch leaves the previously installed toolset active. Checksum verification does not authenticate SHA256SUMS; follow the release/VERIFY.md procedure at the tag you install when authenticity matters. The installer reads these variables; the installed binaries do not.

Name	Purpose	Default or required
EVIDENCECTL_VERSION	Registry Stack tag whose Registry Evidence toolset assets are installed. A published installer pins its own tag.	Defaults to the installer’s pinned tag.
EVIDENCECTL_INSTALL_DIR	Directory that receives the toolset and the evidence, evidencectl, and evidence-oid4vci command symlinks.	Defaults to ~/.local/bin.
EVIDENCECTL_ASSET_DIR	Directory of already-downloaded release assets to use instead of downloading.	Optional.

Evidence OID4VCI supporting service

Name	Purpose	Default or required
EVIDENCE_OID4VCI_RUNTIME_CONFIG	YAML configuration path for evidence-oid4vci check, inspect, and serve. Equivalent to --runtime-config.	Required for those three subcommands, by flag or by variable.
RUST_LOG	Tracing filter installed for every subcommand.	Defaults to info.

Base Registry Engine

The breg binary reads one fixed variable.

Name	Purpose	Default or required
BREG_LOG	Level for the JSON operational records the process writes on standard output.	Defaults to info.

BREG_LOG is a closed enumeration, not a tracing filter directive. It accepts exactly error, warn, and info, and the level applies to the registry_breg target only. Any other value is refused: the process reports that the operational log level was refused and exits with status 2 instead of falling back to info.

Expansion and secret references in runtime.yaml

breg substitutes ${NAME} expressions in the string values of runtime.yaml after parsing it, so a substituted value is always text: it cannot add a key, change a number or boolean, or carry YAML structure, and a line break inside it stays part of the string. A bare ${NAME} refuses the file when the variable is unset or empty, ${NAME:-fallback} substitutes the fallback in that case, and ${NAME:?message} refuses the file with a diagnostic that names NAME and withholds the message, because the message is configuration, which a diagnostic does not repeat. A field whose name ends in Ref and every value under secretProviders refuse an expression, so the environment cannot choose which secret is read or where it comes from. The authored project and module files refuse any ${...} expression, so the reviewed package is the one that runs. A refused substitution stops the process at startup.

Secret references use two grammars: secret:env/<NAME> names an operator-chosen environment variable and secret:file/<name> names a file under the secretProviders.file.root directory. secret:env/<NAME> resolves only when runtime.yaml declares secretProviders.environment; without that declaration the reference is refused. See Deploy a registry for the fields that take a reference.

Bregctl

bregctl reads no fixed environment variable. Projects, runtime files, credentials, and packages arrive through positional paths and explicit flags. Every command that takes --runtime-config loads the runtime file the way breg does, so the ${NAME} expressions in that file resolve from the environment of the bregctl process.

Base Registry Engine installer

The install script reads these variables. They are read by the script, not by the installed binaries.

Name	Purpose	Default or required
BREG_VERSION	Base Registry Engine tag to install. A published installer asset embeds its own tag and refuses an override that does not match it.	Defaults to the installer’s pinned tag.
BREG_INSTALL_DIR	Directory the script installs into.	Defaults to ~/.local/bin.
BREG_ASSET_DIR	Directory of already-downloaded release assets to read instead of downloading. Use it after verifying a release with release/VERIFY.md at that release’s tag.	Optional.

The script verifies the downloaded breg and bregctl binaries against the release SHA256SUMS before anything reaches the install directory. It installs both together or preserves the previous set. It does not verify release authenticity.

Registry Casework

CASEWORK_LOG selects error, warn, or info for JSON operational records on standard output, with info as the default. Other values, including tracing directives and debug, stop startup with exit status 2. The filter covers Casework and its BReg context provider.

Pass the runtime file explicitly with casework --runtime-config <FILE> serve or caseworkctl doctor --runtime-config <FILE>. Casework has no fixed environment variable for that path. Enable secretProviders.environment explicitly before using an operator-chosen secret:env/NAME; file-backed secrets require secretProviders.file.root. caseworkctl uses command arguments and the runtime’s declared secret providers rather than a fixed logging or runtime-path variable.

Registry Messaging

MESSAGING_LOG selects error, warn, or info for JSON operational records on standard error, with info as the default. Other values, including an empty value, tracing directives, and debug, stop messaging serve with exit status 2 before it reads its runtime configuration; messaging --version and --help answer whatever the variable holds. The level covers the Messaging crates only; a dependency’s log lines never reach the stream. A messagingctl dev session reads the same variable and writes the records to the session’s private log file instead.

Pass the runtime file explicitly with messaging --runtime-config <FILE> serve. Messaging has no fixed environment variable for that path.

Registry Document Store

DOCUMENTS_LOG selects error, warn, or info for JSON operational records on standard error, with info as the default. Other values, including an empty value, tracing directives, and debug, stop documents serve with exit status 2 before it reads its runtime configuration; documents --version and --help answer whatever the variable holds. The level covers the Document Store crates only; a dependency’s log lines never reach the stream.

Pass the runtime file explicitly with documents --runtime-config <FILE> serve or documentsctl plan --runtime-config <FILE>. The Document Store has no fixed environment variable for that path, and documentsctl reads no logging variable.

Base Registry Engine citizen gateway

breg-mcp and breg-review are supporting services beside the Base Registry Engine: an MCP gateway a chat host uses to read a citizen’s own data and prepare a native Proposal draft, and a review page the citizen submits it from. Each reads one fixed variable for its operational log level.

Name	Purpose	Default or required
BREG_MCP_LOG	Level for the JSON operational records breg-mcp writes on standard output.	Defaults to info.
BREG_REVIEW_LOG	Level for the JSON operational records breg-review writes on standard output.	Defaults to info.

Both are closed enumerations, not tracing filter directives. Each accepts exactly error, warn, and info; any other value is refused, and the process reports the error on standard error and exits with status 2 instead of falling back to info. BREG_REVIEW_LOG applies to the breg_review and registry_breg_review targets. A runtime configuration that cannot be loaded stops either process with status 1, reported on standard error. Citizen chat assistant names the records worth watching.

Both services use the shared runtime loader for ${VAR}, ${VAR:-default}, and ${VAR:?message} in ordinary string values. Fields ending in Ref or Refs and all of secretProviders refuse environment expressions. Credential values come from their declared secret:env/ or secret:file/ provider. See configure the citizen chat assistant.

Source

The fixed names above are transcribed from the retained binary entry points, runtime loaders, and install scripts. Registry Evidence definitions live in crates/registry-evidence, Evidence tooling in crates/registry-evidencectl, and Base Registry Engine definitions in crates/registry-breg and crates/registry-bregctl.