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.

Authority after Enterprise registration¶

Registration is a permanent authority transition for that Runtime Home:

Post-registration class	Variables
Retained for a separate operational role	`RUNTIME_HOME`; `RUNTIME_PORTAL_API_KEY`; `RUNTIME_CONSUMER`, `RUNTIME_ACTOR_NAME`, `RUNTIME_SESSION_ID`; external-tool credentials/context such as `RUNTIME_GITHUB_TOKEN` and `KUBECONFIG`; `RUNTIME_AUDIT_MAX_UNDELIVERED_BYTES`
Rejected	`RUNTIME_CONFIG_FILE`, `RUNTIME_POLICY_FILE`
No longer configuration or capability authority	`RUNTIME_CAPABILITIES_DIR`; `RUNTIME_RUNTIME_`; `RUNTIME_AUTHENTICATION_`; `RUNTIME_AUDIT_DELIVERY_MODE`; `RUNTIME_PORTAL_ENABLED`, `RUNTIME_PORTAL_BASE_URL`, `RUNTIME_PORTAL_PATH_PREFIX`, `RUNTIME_PORTAL_TIMEOUT_SECONDS`

The enrollment marker supplies the pinned Portal origin and the last verified atomic generation supplies policy, managed configuration, and capability sources. Local Home files and ambient config overrides cannot replace them.

Quick index¶

Variable	Purpose
`RUNTIME_HOME`	Where the Runtime Home lives
`RUNTIME_CAPABILITIES_DIR`	Selects one authoritative capability directory
`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_PORTAL_*`	Optional control-plane client (off by default)
`RUNTIME_PORTAL_API_KEY`	One-Runtime credential for registration, heartbeat and governance sync
`RUNTIME_*`	Registered `config.yaml` keys only
`RUNTIME_CONSUMER`	`human` / `ci` / `ai`, recorded on every audit record
`RUNTIME_ACTOR_NAME`	Optional self-asserted actor label
`RUNTIME_SESSION_ID`	Optional CI/agent/session correlation ID
`CI`	Standard fallback for `RUNTIME_CONSUMER=ci`
`USER` / `USERNAME`	Separate observed audit executor and default actor label

Location overrides¶

`RUNTIME_HOME`¶

Where the Runtime Home lives — Runtime-owned contracts, the audit log, and working state. Not config, policy, context, credentials, or the authoritative capability library.

Default: ~/.engineering-runtime

export RUNTIME_HOME=/tmp/runtime-home
runtime bootstrap

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

ENGINEERING_RUNTIME_HOME is a deprecated pre-v1 compatibility alias. If both names are set, equal values are accepted and different values refuse. New automation must use RUNTIME_HOME.

`RUNTIME_CONTEXT_FILE` — retired¶

This former context-document override is intentionally blocking. Runtime now observes native tool context; unset the variable and run runtime context retire for migration guidance.

`RUNTIME_CAPABILITIES_DIR`¶

Before Enterprise enrollment, selects one ordinary authoritative capability directory. Runtime resolves names from it, reports it as capabilities-dir, and uses it as the default authoring source. Runtime never fetches or seeds examples there.

When unset: Runtime falls back to the non-authoritative <Runtime Home>/capabilities cache.

export RUNTIME_CAPABILITIES_DIR=/tmp/runtime-capabilities
runtime bootstrap
runtime capability list

Since Runtime 0.9.2 this is the ordinary setup, not a cache hint. A directory named here is an authoritative source — capability list reports it as capabilities-dir — and it is where new capabilities are written. Setting it is the whole configuration: no config.yaml edit, and no file_policy.write_roots grant, because authoring is you editing a file with your own tools rather than the File Engine acting on your behalf.

Runtime never fetches it. Clone and pull it yourself; Runtime reads whatever is on disk and records the digest of exactly those bytes.

After enrollment this variable is not consulted; signed capabilities.sources is the executable capability-source authority.

Use capabilities.sources when you run several directories at once — they are searched in order, first match wins — and name the one you author into with capabilities.authoring_source. With one directory that key is unnecessary; with several, Runtime asks rather than guessing. 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 in Community/local mode. It is rejected after Enterprise enrollment.

export RUNTIME_CONFIG_FILE=/path/to/config.yaml

`RUNTIME_POLICY_FILE`¶

Absolute path to a policy-config.yaml outside the Runtime Home. It is rejected after Enterprise enrollment.

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` — native gh or brokered Runtime inputs¶

For provider-chosen gh operations, Runtime validates the configured GitHub credential and brokers it as GH_TOKEN and GITHUB_TOKEN.

For the direct gh.repo.list mode, Runtime also preserves native gh behaviour: an existing GH_TOKEN/GITHUB_TOKEN or gh credential-store session can be used when no configured RUNTIME_GITHUB_TOKEN is populated. Runtime validates the session with gh auth status, marks credential values secret at the process boundary, and never starts gh auth login.

`RUNTIME_PORTAL_API_KEY`¶

The show-once erk_rt_v1_… key used as X-API-Key for one Runtime's registration, heartbeat, and signed governance sync. It is a credential, not a config key: it never belongs in config.yaml, and there is no portal.api_key setting.

Create it from the authenticated Control Plane API Keys screen and export it in that Runtime's process/secret environment. Bearer, cookie and query credentials are not Runtime machine authentication.

export RUNTIME_PORTAL_API_KEY=erk_rt_v1_…
runtime portal register

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

What a tool run by `command run` receives¶

Not your environment. Since 0.6.0 the Command Engine builds a process environment instead of passing on its own, so a variable exported in your shell does not reach the tool unless it is admitted.

Class	What reaches the tool
Baseline	`LANG`, `LC_*`, `TERM`, `TZ`, plus a fixed minimal `PATH`, a private `TMPDIR`, and non-interactive flags
Declared by the tool's contract	Only the names the runtime carries for that tool — `KUBECONFIG` for `kubectl`/`oc`/`helm`, `CLOUDSDK_CONFIG` and `GOOGLE_APPLICATION_CREDENTIALS` for the Cloud SDK, `VAULT_ADDR`/`VAULT_TOKEN` for `vault`, and so on
Narrowed by policy	`command_policy.rules.<binary>.environment` can shorten that list. An absent list means the contract decides; an empty list means nothing at all
Set by containment	Values Runtime fixes to switch off a tool's own child-launching mechanisms — `GIT_CONFIG_*` pinning `core.hooksPath` off, `HELM_PLUGINS` pointed at an empty directory, `CLOUDSDK_CORE_DISABLE_PROMPTS` and `CLOUDSDK_COMPONENT_MANAGER_DISABLE_UPDATE_CHECK`. These are applied last, so an ambient value cannot re-open them
Refused for everyone	`LD_PRELOAD`, `LD_LIBRARY_PATH`, `DYLD_*`, `BASH_ENV`, `PYTHONPATH`, `PYTHONSTARTUP`, `RUBYOPT`, `PERL5OPT`, `NODE_OPTIONS`, `GIT_SSH`, `GIT_SSH_COMMAND`, `GIT_EXTERNAL_DIFF`, `PAGER`, `EDITOR`, `VISUAL`. No policy — not even an enterprise one — may forward these: each of them redirects what an approved binary executes

SSH_AUTH_SOCK and other agent sockets are absent by default.

Upgrading from 0.5.x

A command run that quietly depended on an ambient variable now fails. That is the intended breaking change: the alternative is every approved binary keeping access to every secret in your shell. Add the name to that binary's environment list — and if the runtime carries no contract naming it for that tool, the variable cannot be forwarded at all, which is also deliberate.

Config key overrides¶

Before Enterprise enrollment, only registered keys have an environment spelling, written out rather than derived. The environment wins over the file — useful when the file is read-only or absent in CI. An unregistered RUNTIME_* variable does nothing. After enrollment these config-key variables do not override the verified managed generation.

`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`	`""`

`audit`¶

The first managed key. A local operator may opt in to collector-required. Once a verified enterprise generation requires collection, that value is a floor: this variable cannot lower it.

Variable	Config key	Default
`RUNTIME_AUDIT_DELIVERY_MODE`	`audit.delivery_mode`	`local`

collector-required has no exporter in this release. It never uses the Portal client or RUNTIME_PORTAL_API_KEY; future external delivery is a separate OpenTelemetry integration with exporter credentials.

Audit identity and correlation¶

`RUNTIME_CONSUMER`¶

Sets the caller class: human, ci, or ai. When unset, a non-empty CI selects ci; otherwise the default is human.

ENGINEERING_RUNTIME_CONSUMER is a deprecated compatibility alias. Equal dual values are accepted; conflicting values refuse.

`RUNTIME_ACTOR_NAME`¶

Sets an optional readable operator, workload, or agent label. When absent, Runtime uses $USER, then $USERNAME, then unknown. It is always recorded with actor_assurance=self_asserted: useful for search and correlation, never an authorization identity.

`RUNTIME_SESSION_ID`¶

Correlates one shell, CI run, agent task, or pod execution. Runtime does not guess vendor-specific variables; map the native value explicitly:

export RUNTIME_CONSUMER=ci
export RUNTIME_ACTOR_NAME=production-release
export RUNTIME_SESSION_ID="$GITHUB_RUN_ID"

CI is the standard fallback signal for consumer kind. $USER and Windows $USERNAME remain separately recorded as executor; the actor label does not overwrite that observation.

`portal`¶

The optional control-plane client, off by default. These four are registered config overrides; RUNTIME_PORTAL_API_KEY is the separate secret credential kept out of configuration files.

Variable	Config key	Default
`RUNTIME_PORTAL_ENABLED`	`portal.enabled`	`false`
`RUNTIME_PORTAL_BASE_URL`	`portal.base_url`	`""`
`RUNTIME_PORTAL_PATH_PREFIX`	`portal.path_prefix`	`/api/v1`
`RUNTIME_PORTAL_TIMEOUT_SECONDS`	`portal.timeout_seconds`	`5`

export RUNTIME_PORTAL_ENABLED=true
export RUNTIME_PORTAL_BASE_URL=https://customer-control-plane.example
export RUNTIME_PORTAL_PATH_PREFIX=/api/v1
export RUNTIME_PORTAL_API_KEY='<show-once-runtime-key>'
runtime portal status

An enabled client requires a non-empty base_url, /api/v1, and a valid key. See Control Plane (Portal).

RUNTIME_PORTAL_BASE_URL is security-relevant

Point it at the company app-api origin, not a UI or the public static API reference. First registration pins organization and signing-key trust; later responses must verify against that anchor.

There is deliberately no environment variable that supplies policy content. Rules arrive either from the policy file or from an explicit portal sync, never from the environment — consistent with policy having no environment overrides.

`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

Recipes¶

Throwaway local homeCI jobGitHub Enterprise

export RUNTIME_HOME=/tmp/runtime-home
runtime bootstrap

export RUNTIME_HOME="$PWD/runtime-home"
export RUNTIME_CONSUMER=ci
export RUNTIME_ACTOR_NAME=production-release
export RUNTIME_SESSION_ID="$GITHUB_RUN_ID"
runtime config validate

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

Operational examples on this site were verified against Runtime 0.9.8. After bootstrap, the version-exact files in Runtime Home win.

Environment Variables¶

Authority after Enterprise registration¶

Quick index¶

Location overrides¶

RUNTIME_HOME¶

RUNTIME_CONTEXT_FILE — retired¶

RUNTIME_CAPABILITIES_DIR¶

RUNTIME_CONFIG_FILE¶

RUNTIME_POLICY_FILE¶

Credentials¶

RUNTIME_GITHUB_TOKEN¶

KUBECONFIG¶

GH_TOKEN / GITHUB_TOKEN — native gh or brokered Runtime inputs¶

RUNTIME_PORTAL_API_KEY¶

GCP and OpenShift — no token variables¶

What a tool run by command run receives¶