Environment variable reference

This page lists Registry Stack’s supported fixed environment-variable interfaces for runtimes, adopter tooling, and installers. It also records how Relayctl keeps fixture scratch state independent of host temporary-directory configuration.

The stack’s other kind of environment variable is operator-named. Secret material such as an audit integrity key is not read from a fixed variable name: a configuration field carries a reference that names the variable, and the operator chooses the name. Relay and Base Registry Engine are the products that work that way, and the reference grammar is closed rather than free-form. Evidence Gateway reads no secret from the environment under either kind of name, as its section records.

Configuration expansion

Relay and Evidence Gateway expand no environment reference inside their configuration documents. Each parses its documents as written: Relay in RelayRuntime::parse_yaml and RegistryContract::parse_yaml (crates/registry-relay-v2/src/contract.rs), and Evidence Gateway in RuntimeConfig::parse_yaml (crates/registry-evidence/src/config.rs). Base Registry Engine is the exception: breg expands ${NAME} expressions in its runtime file at load, as its section records.

Relay

The relay binary reads these variables.

Name	Purpose	Default or required
RELAY_RUNTIME	Path to the deployment binding that names the sealed package, the local sources, authentication, audit, and limits. Equivalent to --runtime on relay check and relay serve.	Required for relay serve, by flag or by variable. relay check defaults to /etc/relay/runtime.yaml.
RELAY_HEALTHCHECK_URL	Complete HTTP or HTTPS URL of the unauthenticated /health endpoint to probe. Equivalent to the --url flag on relay healthcheck.	Defaults to http://127.0.0.1:8080/health.
RELAY_LOG	Level for the JSON operational records the process writes on standard error.	Defaults to info.

RELAY_LOG is a closed enumeration, not a tracing filter directive. It accepts exactly off, error, warn, info, debug, and trace, and each value applies to the registry_relay_v2 target only. Any other value, including a valid-looking directive such as trace,hyper=trace, falls back to info. An arbitrary directive could enable dependency events carrying URLs or headers, so the process refuses to accept one.

Secret references in runtime.yaml

Relay resolves secrets through two providers, environment and file, rooted at the directory holding the runtime file. Two fields take a reference: audit.integrityKeyRef, which is required, and cursor.integrityKeyRef, which applies when the deployment enables cursors.

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

A reference that matches neither grammar makes the runtime document invalid, so the process refuses to start rather than serving with an unresolved secret. The variable names themselves are the operator’s choice and appear nowhere in Relay’s source. See Configure Relay for the fields around them.

Relay installer

The install script reads these variables. They are read by the script, not by the running binary.

Name	Purpose	Default or required
RELAY_VERSION	Relay 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.
RELAY_INSTALL_DIR	Directory the script installs into.	Defaults to ~/.local/bin.
RELAY_ASSET_DIR	Directory of already-downloaded release assets to read instead of downloading. Use it after verifying a release with release/VERIFY.md.	Optional.

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

Relayctl

relayctl reads no environment variable. Workflow registries and projects arrive through positional paths, explicit flags, or authored files. tooling editor may use its documented current-directory default, and the language server receives authoring documents through its protocol session. Secret references remain inside the project’s runtime.yaml for relay to resolve at startup.

relayctl test ignores host temporary-directory variables. It validates the canonical project’s parent hierarchy, creates an owner-only transient workspace beside the project, and removes that workspace after the fixture run. The project itself may be read-only, but its parent must be trusted and writable. Scratch placement cannot select a Registry, deployment environment, credential, or governed behavior.

Evidence Gateway

The runtime-path option is global. EVIDENCE_LOG is read by evidence serve only.

Name	Purpose	Default or required
REGISTRY_EVIDENCE_RUNTIME	Absolute path to the one operator runtime file that binds the governed bundle. Equivalent to the global --runtime flag.	Defaults to /etc/registry-evidence/runtime.yaml.
EVIDENCE_LOG	Tracing filter for the operational records the serving process writes as line-delimited JSON on standard output.	Defaults to info. Read by evidence serve only; offline commands install no log subscriber.

Evidence Gateway reads no secret from an environment variable. A configured secret reference uses one grammar, secret:file/<name>, enforced by SecretRef::parse in crates/registry-evidence/src/config.rs, and resolves through registry-platform-config to an owner-only regular file under the secretProviders.file.root directory named in runtime.yaml. Neither the runtime file nor the governed bundle can name an environment variable to read a credential from. See Configure Evidence Gateway 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.

Evidence Gateway toolset installer

The Evidence Gateway toolset installer stages evidence, evidencectl, and evidence-oid4vci, then verifies every binary against SHA256SUMS before replacement begins. If a replacement fails, it attempts to restore the previous three-binary set. Checksum verification does not authenticate SHA256SUMS; follow the tag-frozen release/VERIFY.md procedure when authenticity matters. The installer reads these variables; the installed binaries do not.

Name	Purpose	Default or required
EVIDENCECTL_VERSION	Registry Stack tag whose Evidence Gateway 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 three binaries.	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_CONFIG	YAML configuration path for evidence-oid4vci check, inspect, and serve. Equivalent to --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 expands ${NAME} expressions in runtime.yaml before parsing it. 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 that message. A value that fills a whole YAML scalar is inserted as a quoted scalar. A value embedded in a longer scalar is refused when it carries anything YAML could read as structure: a line break, a quote or backtick, a brace or bracket, a comma, | or >, a colon followed by a space, a space followed by #, or a leading #, &, *, !, %, @, ---, or .... A refused expansion stops the process at startup.

Secret references use the same two grammars as Relay: secret:env/<NAME> names an operator-chosen environment variable and secret:file/<name> 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.	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.

Source

The fixed environment variable names in this reference are transcribed from the CLI definitions, binary entry points, and install scripts. Relay CLI ownership is in crates/registry-relay-v2/src/cli.rs, with logging in main.rs, secret grammar in contract.rs, and resolution in startup.rs. Evidence CLI ownership is in crates/registry-evidence/src/cli.rs, logging in main.rs, and file-secret resolution in registry-platform-config. Evidencectl binary selection is in crates/registry-evidencectl/src/evidence_binary.rs; its installer is crates/registry-evidencectl/install.sh. OID4VCI CLI ownership is in crates/registry-evidence-oid4vci/src/cli.rs, with logging and dispatch in main.rs. Base Registry Engine logging is in crates/registry-breg/src/main.rs and startup.rs, runtime-file expansion and the secret grammar in runtime_config.rs over registry-platform-config, and its installer is crates/registry-breg/install.sh.