Skip to content

Environment Variables

Every variable the runtime reads, grouped by purpose.

Tokens never go in config.yaml. Path overrides and config-key overrides do. Policy has no environment overrides at all — see Policy.

Quick index

Variable Purpose
ENGINEERING_RUNTIME_HOME Where the Runtime Home lives
RUNTIME_CAPABILITIES_DIR Where capabilities are seeded and resolved
RUNTIME_CONFIG_FILE An external config.yaml
RUNTIME_POLICY_FILE An external policy-config.yaml
RUNTIME_GITHUB_TOKEN GitHub credential
KUBECONFIG Kubernetes credential source
RUNTIME_* Any config.yaml key
ENGINEERING_RUNTIME_CONSUMER human / ci / ai, recorded on every audit record
CI Standard CI indicator
USER / USERNAME Audit executor

Location overrides

ENGINEERING_RUNTIME_HOME

Where the Runtime Home lives — config, policy, context, logs, specs, commands, and (unless relocated) capabilities.

Default: ~/.engineering-runtime

export ENGINEERING_RUNTIME_HOME=/tmp/runtime-home
runtime bootstrap

Useful for local testing, throwaway sandboxes, and per-job CI homes.

RUNTIME_CAPABILITIES_DIR

Where capabilities are seeded into and resolved from. Deliberately separate from the Runtime Home so a team can share one version-controlled capabilities directory without relocating runtime state.

Default: <Runtime Home>/capabilities

export RUNTIME_CAPABILITIES_DIR=~/work/team-capabilities
runtime bootstrap
runtime capability execute github/repo-health --input repository=cli/cli

See Sharing a Capability Directory.

RUNTIME_CONFIG_FILE

Absolute path to a config.yaml outside the Runtime Home. When set, this file is used instead of <home>/config.yaml.

export RUNTIME_CONFIG_FILE=/path/to/config.yaml

RUNTIME_POLICY_FILE

Absolute path to a policy-config.yaml outside the Runtime Home.

export RUNTIME_POLICY_FILE=/path/to/policy-config.yaml

This is the only way to change policy from the environment

Individual policy rules are never overridable by an environment variable. An env var must never be able to widen governance — so changing policy always means pointing at a different file, which is a reviewable artifact.

Credentials

RUNTIME_GITHUB_TOKEN

The GitHub personal access token (classic or fine-grained) read by the Auth Engine. Validated against GET <base_url>/user.

export RUNTIME_GITHUB_TOKEN=ghp_your_personal_access_token

The token value is never stored in config.yaml — only the name of this variable is (authentication.github.token_env). Override the name itself if a pipeline already exports a differently named token:

export RUNTIME_AUTHENTICATION_GITHUB_TOKEN_ENV=MY_EXISTING_PAT

KUBECONFIG

Standard kubectl/oc kubeconfig path. Used as the default for authentication.kubernetes.kubeconfig_path when that key is empty. Falls back to ~/.kube/config when unset.

export KUBECONFIG=~/.kube/config

GH_TOKEN / GITHUB_TOKEN — not runtime inputs

When the Command Engine runs gh, it forwards the already-validated GitHub token as GH_TOKEN and GITHUB_TOKEN, so gh never needs its own gh auth login. Export RUNTIME_GITHUB_TOKEN instead — these two are outputs of the runtime, not inputs to it.

GCP and OpenShift — no token variables

Those providers validate platform-native sessions the tools already manage:

gcloud auth application-default login      # GCP
oc login --token=<token> --server=<url>    # OpenShift

Config key overrides

Every key in config.yaml is also settable as RUNTIME_<KEY>, dots replaced by underscores. The environment wins over the file — useful when the file is read-only or absent in CI.

runtime

Variable Config key Default
RUNTIME_RUNTIME_NAME runtime.name engineering-runtime
RUNTIME_RUNTIME_LOG_LEVEL runtime.log_level info

authentication

Variable Config key Default
RUNTIME_AUTHENTICATION_PROVIDER authentication.provider github
RUNTIME_AUTHENTICATION_GITHUB_ENABLED authentication.github.enabled true
RUNTIME_AUTHENTICATION_GITHUB_BASE_URL authentication.github.base_url https://api.github.com
RUNTIME_AUTHENTICATION_GITHUB_TOKEN_ENV authentication.github.token_env RUNTIME_GITHUB_TOKEN
RUNTIME_AUTHENTICATION_GCP_ENABLED authentication.gcp.enabled false
RUNTIME_AUTHENTICATION_GCP_BINARY authentication.gcp.binary gcloud
RUNTIME_AUTHENTICATION_KUBERNETES_ENABLED authentication.kubernetes.enabled false
RUNTIME_AUTHENTICATION_KUBERNETES_KUBECONFIG_PATH authentication.kubernetes.kubeconfig_path ""
RUNTIME_AUTHENTICATION_OPENSHIFT_ENABLED authentication.openshift.enabled false
RUNTIME_AUTHENTICATION_OPENSHIFT_BINARY authentication.openshift.binary oc
RUNTIME_AUTHENTICATION_OPENSHIFT_SERVER authentication.openshift.server ""

command_providers

A nested map, awkward to express in a single variable. Edit config.yaml for this one:

command_providers:
  gh: github
  gcloud: gcp
  kubectl: kubernetes
  oc: openshift
  terraform: none

Audit and identity

ENGINEERING_RUNTIME_CONSUMER

Who or what is driving the runtime. Recorded on every audit record as consumer.

Values: human | ci | ai When unset: ci if CI is set, otherwise human.

export ENGINEERING_RUNTIME_CONSUMER=ai

CI

Standard CI indicator (any non-empty value). When ENGINEERING_RUNTIME_CONSUMER is unset and CI is set, the audit consumer becomes ci. Most CI systems export this automatically.

USER / USERNAME

OS username, recorded on audit records as executor. Resolution order: $USER, then $USERNAME (Windows), else unknown. Normally set by your shell — rarely needs exporting by hand.

Recipes

export ENGINEERING_RUNTIME_HOME=/tmp/runtime-home
export RUNTIME_CAPABILITIES_DIR=~/work/team-capabilities
runtime bootstrap

export ENGINEERING_RUNTIME_HOME="$PWD/runtime-home"
export RUNTIME_CONFIG_FILE="$PWD/runtime-home/config.yaml"
export RUNTIME_POLICY_FILE="$PWD/runtime-home/policy-config.yaml"
export RUNTIME_GITHUB_TOKEN="$GITHUB_PAT"
export ENGINEERING_RUNTIME_CONSUMER=ci
runtime config validate

export RUNTIME_AUTHENTICATION_GITHUB_BASE_URL=https://ghe.example.com/api/v3
export RUNTIME_GITHUB_TOKEN=ghp_xxx
runtime auth status