Skip to content
kratex
Docs menu

Environment variables

Kratex reads a small, fixed set of environment variables: some user-facing, some set internally by the CLI when it spawns a guarded child process, and a few well-known platform variables it observes for compatibility with existing tooling. Every read site is in cli/src/ or runtime/src/; nothing is consulted dynamically by name.

This page is the authoritative list. If a variable name starts with KRATEX_ and is not on this page, Kratex does not read it.

Kratex-owned variables (user-facing)

These are safe to set. Each has a defined value space and a defined effect.

VariableValuesDefaultDescription
KRATEX_MODEaudit | enforce(policy file)Read only by the preload when it installs guards; no CLI command reads it, and kratex run / install / ci overwrite it on the child with the resolved mode (CLI flag, then policy file). Setting it before a kratex command has no effect. It applies only when you launch node --import with KRATEX_REGISTER=1 yourself.
KRATEX_DEBUG1unsetWhen 1, emits one or two startup lines to stderr on preload: installed policy summary and inherited exposure baseline, if any. Not continuous verbose output.
KRATEX_QUIET1unsetWhen 1, suppresses the [kratex] active policy: … banner on kratex run / kratex install / kratex ci. Useful in CI where banner output is noise.
KRATEX_CONFIG_HOMEdirectory path(platform config dir)Overrides only the scratch directory for transient runtime state, currently a telemetry sink’s on-disk retry queue. It does not move the per-machine install-id or the rules cache; those live under the platform config directory, which honors XDG_CONFIG_HOME on all platforms and APPDATA on Windows.
KRATEX_NO_COLOR1unsetWhen 1, disables ANSI color in formatted event output. Takes precedence over the standard NO_COLOR and TERM=dumb. See color output precedence.

Kratex-owned variables (internal: do not set)

These are set by Kratex on spawned child processes. Setting them manually does nothing useful and can break attribution.

VariableSet byPurpose
KRATEX_REGISTERkratex run / runtime spawnWhen 1, the CLI binary’s dual-mode entry point activates preload mode (loads policy, installs guards) instead of CLI mode. Paired with --import (Node 20.6+) or --require (older).
KRATEX_PHASEkratex install, kratex ci, kratex runinstall switches built-in rules to the install-lifecycle set; anything else (including runtime) collapses to runtime. The runtime recognizes only those two states.
KRATEX_RUN_IDkratex run (and other top-level commands)UUID that correlates telemetry events emitted by the parent CLI process and the spawned guarded child. Joining events on this ID is how the operator-visible caller-chain story stays whole across the process boundary.
KRATEX_PROCESS_EXPOSUREruntime, on every guarded spawnComma-separated exposure labels, which are data-class ids (e.g. secrets,wallet), propagated from parent to guarded child. Do not set manually. Whenever the runtime computes a non-empty baseline from the authoritative caller chain, it overwrites any caller-supplied value on the spawn. Letting a third-party launder its exposure by passing a stripped value would defeat caller-chain attribution.
KRATEX_RESOLVED_CONFIGkratex run / install / ciThe policy file path the parent already resolved, handed to the child so the preload reuses that resolution instead of re-discovering it.
KRATEX_PLATFORM_SHELLkratex run / install / ciThe platform shell the parent resolved, propagated so the child attributes shell spawns consistently.
KRATEX_WORKER_ORIGINruntime, on worker-thread creationIdentity of the package that constructed a Worker, propagated so the worker’s operations attribute to that caller rather than to the worker entry point.

KRATEX_MODE is listed in the user-facing table above; the CLI also sets it on every guarded child, alongside KRATEX_PHASE. See kratex run for the full propagation list.

Color output precedence

The runtime’s event formatter decides whether to emit ANSI color in this order, first matching rule wins:

  1. KRATEX_NO_COLOR=1: Kratex-specific kill switch. Disables color.
  2. NO_COLOR set to any non-empty value: no-color.org standard. Disables color.
  3. TERM=dumb: terminal type hint. Disables color.
  4. TTY detection: stream.isTTY. Color only if the output stream is a TTY.

KRATEX_NO_COLOR=1 is the override for the case where you want color on a TTY in general (so NO_COLOR would be too coarse) but not from Kratex specifically.

CI detection

Kratex reads a closed list of nine env-var names to populate the ci field on the condition context (used by the ci condition in policy):

CI, CONTINUOUS_INTEGRATION, GITHUB_ACTIONS, GITLAB_CI, BUILDKITE, CIRCLECI, TF_BUILD, JENKINS_URL, TEAMCITY_VERSION.

The truthiness test treats undefined, the empty string, "false", and "0" as not-CI; anything else counts. Travis CI, AppVeyor, Drone, and other vendors not on the list only match via the generic CI=true that all of them set.

For the matching operator and example policy snippets, see Policy authoring → Conditions.

Platform variables Kratex reads

Four well-known platform variables affect Kratex’s behavior:

VariableHow Kratex uses it
PATHRead inside the guarded child to resolve a spawn() target when the command is a bare name (no /, no absolute path). Used purely for attribution: Kratex needs to know which binary the call resolves to.
NODE_OPTIONSThe parent process’s NODE_OPTIONS is forwarded to spawned children with the Kratex preload flag (--import=… on Node 20.6+, --require=… on older) prepended. Any options you set on the parent reach the child unchanged; the prepended flag is what keeps the guard in place across the spawn boundary. See kratex run.
XDG_CONFIG_HOMEWhen set (any platform), the platform config directory becomes $XDG_CONFIG_HOME/kratex. That directory holds the per-machine install-id and the rules cache consulted during policy file discovery.
APPDATAOn Windows, when XDG_CONFIG_HOME is unset, the platform config directory is %APPDATA%\Kratex, with the same contents as above.

See also