Runtime Context

Runtime context is the information available when a stack is loaded or resolved: the launching process environment, selected stack names, selected platform, search directories, and explicitly defined stack values. Modifiers select and compose those values; YAML tags encode, decode, encrypt, or hash representations. See Variable expansion for their syntax and evaluation order.

Context and Stack Data

ROOT, ENV, HOME, and USER are ordinary variable names. A stack can define them, use a self-reference to inherit them, or leave them absent so references can fall back to the process environment. envstack does not inject a complete runtime-variable dictionary into every loaded stack.

Likewise, PLATFORM inside a stack is ordinary data. Selecting --platform windows or load_environ(..., platform="windows") chooses YAML sections and path delimiters; it does not create or overwrite a PLATFORM variable. Changing that variable does not change platform selection.

STACK is special: loading supplies the last requested stack name when the merged stack has no truthy STACK value. A nonempty value defined in a stack is preserved. Treat STACK as loader metadata rather than using it for unrelated application data.

Runtime Controls

Set import-time controls in the launching shell before starting envstack, or before importing it in Python. A same-named value inside a stack is still data; it does not reconfigure constants already read by the running process.

Name	Purpose and timing
`ENVPATH`	Search directories, separated by the host’s path delimiter. Read when loading; a resolved stack `ENVPATH` can affect subsequent requested stacks. The current directory is also searched.
`DEFAULT_NAMESPACE`	Default stack name, read at import time; defaults to `default`. Explicit stack arguments override it.
`ALLOW_COMMANDS`	Enable `$(...)`, read at import time; disabled by default. Values `1`, `true`, `True`, and `TRUE` enable it.
`COMMAND_TIMEOUT`	Command timeout in seconds, read at import time; defaults to 5, including when the setting is not an integer.
`IGNORE_MISSING`	Ignore missing stack files, read at import time; enabled by default. Uses the same true values as `ALLOW_COMMANDS`. The Python loading API can override it.
`LOG_LEVEL`	Logging level read at import time; defaults to `INFO`.
`INTERACTIVE`	Read from a command wrapper’s environment to select interactive command execution.
`SHELL` / `ComSpec`	Host shell detection at import time: `SHELL` on POSIX and `ComSpec` on Windows.
`ENVSTACK_SHELL`	Override the shell selected when launching an envstack shell session.
`ENVSTACK_SYMMETRIC_KEY`	AES-GCM key used during encryption/decryption.
`ENVSTACK_FERNET_KEY`	Fernet key used during encryption/decryption.

Enabling command substitution in a stack with ALLOW_COMMANDS: 1 does not enable it for the process currently loading that file. Exporting that value can influence a subsequently launched envstack process.

Runtime Names and Collisions

Use application-specific names, such as MYAPP_CACHE_ROOT, for application settings. Keep ENVSTACK_* for envstack integration, and avoid repurposing the runtime control names above. This is naming guidance, not an enforced reserved namespace: the loader does not reject these keys or emit collision warnings. There is no separate runtime lookup syntax or implicit ENVSTACK_* variable expansion mechanism.

The current collision behavior is:

Ordinary references prefer stack definitions over shell values. An explicit empty string also wins. A missing variable can fall back to the shell.
A self-reference uses preceding stack definitions before the shell.
Import-time control settings and same-named stack data can differ. For example, a stack’s LOG_LEVEL does not automatically reconfigure the current logger.
For decryption, process-environment encryption keys override matching stack keys. Do not use key names for unrelated data.
A nonempty stack-defined STACK overrides the loader’s default metadata value.

No new collision rejection or reserved-prefix enforcement is introduced by this model. Applications should not assume that writing a runtime-looking name inside a stack changes envstack’s own state.

Inspect Before Applying

envstack myapp -u ROOT ENV DEPLOY_ROOT
envstack myapp -r ROOT ENV DEPLOY_ROOT

The first command displays stored values; the second displays resolved values. Both load the stack, so enabled commands may run during internal ENVPATH resolution. Neither command changes the invoking shell’s environment.

For an application process, use envstack myapp -- command, or apply a stack inside Python with envstack.init("myapp"). The Python API describes loading, resolution, activation, and restoration.