Skip to content

Environment Variables

Runtime v0.9.9's optional GCP/Kubernetes source configuration keys have no environment overrides. Explicit in_cluster additionally consumes native KUBERNETES_SERVICE_HOST (Service IP) and KUBERNETES_SERVICE_PORT, together with the projected CA/namespace/token mount. Those hints alone admit no source. For governed GCP native sources, unrelated GOOGLE_APPLICATION_CREDENTIALS is cleared in the prepared child; the initial REST binding does not substitute ADC. See source admission.

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 ENGRT_HOME; ENGRT_PORTAL_API_KEY; ENGRT_CONSUMER, ENGRT_ACTOR_NAME, ENGRT_SESSION_ID; external-tool credentials/context such as ENGRT_GITHUB_TOKEN and KUBECONFIG; ENGRT_AUDIT_MAX_UNDELIVERED_BYTES
Rejected ENGRT_CONFIG_FILE, ENGRT_POLICY_FILE
No longer configuration or capability authority ENGRT_CAPABILITIES_DIR; ENGRT_NAME, ENGRT_LOG_LEVEL; ENGRT_AUTHENTICATION_*; ENGRT_AUDIT_DELIVERY_MODE; ENGRT_PORTAL_ENABLED, ENGRT_PORTAL_BASE_URL, ENGRT_PORTAL_PATH_PREFIX, ENGRT_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
ENGRT_HOME Where the Runtime Home lives
ENGRT_CAPABILITIES_DIR Selects one authoritative capability directory
ENGRT_CONFIG_FILE An external config.yaml
ENGRT_POLICY_FILE An external policy-config.yaml
ENGRT_GITHUB_TOKEN GitHub credential
KUBECONFIG Kubernetes credential source
ENGRT_PORTAL_* Optional control-plane client (off by default)
ENGRT_PORTAL_API_KEY One-Runtime credential for registration, heartbeat and governance sync
ENGRT_* Registered config.yaml keys only
ENGRT_CONSUMER human / ci / ai, recorded on every audit record (undeclared when unset and nothing is detected)
ENGRT_ACTOR_NAME Optional self-asserted actor label
ENGRT_SESSION_ID Optional CI/agent/session correlation ID
CI Standard fallback for ENGRT_CONSUMER=ci
GITHUB_ACTIONS / GITLAB_CI / KUBERNETES_SERVICE_HOST Non-authoritative execution-location hints; see below
USER / USERNAME Separate observed audit executor and default actor label

Execution-location hints — v0.9.9

For the internal per-invocation context, CI, GITHUB_ACTIONS and GITLAB_CI recognize case-insensitive true or 1. CI is the generic class; exactly one enabled platform marker adds github-actions or gitlab-ci. Conflicting platform markers retain generic CI only. Nonempty KUBERNETES_SERVICE_HOST adds a Kubernetes observation without retaining its raw value or admitting it as an API destination. CI and Kubernetes can coexist; CI has display precedence. An unmarked host is local, not verified laptop identity; absent observations are unknown.

These hints neither enable authentication nor select credentials or permissions, and they are not automatically passed to native tools. Detection does not certify GitLab CI, GKE or in-cluster kubectl support. Existing native setup still applies. The separate audit-consumer convention is unchanged: any nonempty CI supplies the ci consumer fallback when no explicit consumer is configured.

Location overrides

ENGRT_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: ~/.engrt

export ENGRT_HOME=/tmp/runtime-home
engrt bootstrap

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

Since v0.10.0, Runtime reads only ENGRT_* names. Older RUNTIME_* and ENGINEERING_RUNTIME_* names are ignored, not aliased: rename them when you upgrade.

RUNTIME_CONTEXT_FILE — retired

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

ENGRT_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 ENGRT_CAPABILITIES_DIR=/tmp/runtime-capabilities
engrt bootstrap
engrt 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.

ENGRT_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 ENGRT_CONFIG_FILE=/path/to/config.yaml

ENGRT_POLICY_FILE

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

export ENGRT_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

ENGRT_GITHUB_TOKEN

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

export ENGRT_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 ENGRT_AUTHENTICATION_GITHUB_TOKEN_ENV=MY_EXISTING_PAT

v0.12.0 inputs

These are read by v0.12.0 and later; see Governed authority. Values are never echoed.

Variable Purpose
ENGRT_GITHUB_TOKEN_FILE Path to a protected file holding one GitHub token (source: file; derived as <token_env>_FILE)
ENGRT_GITHUB_CREDENTIALS_FILE Path to a protected GitHub credentials document (source: file)
ENGRT_GITHUB_APP_PRIVATE_KEY_FILE Path to a protected GitHub App private key (source: github_app, preferred)
ENGRT_GITHUB_APP_PRIVATE_KEY_B64 Strict base64 GitHub App private key (source: github_app, fallback)
ENGRT_EXECUTION_SURFACE Declared execution surface (local, ci, kubernetes); declared, never proof

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 ENGRT_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.

ENGRT_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 ENGRT_PORTAL_API_KEY=erk_rt_v1_…
engrt portal register

GCP and OpenShift — no token variables

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

gcloud auth login                          # GCP CLI credentials, not ADC
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.

GCP credential/configuration selection (v0.9.9)

Runtime v0.9.9's gcloud contract also admits CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE, subject to the same per-binary environment policy. Google's GitHub auth action exports this path for native gcloud; its separate GOOGLE_APPLICATION_CREDENTIALS setting is for ADC consumers. Runtime forwards the selected path, not the file's contents. The File Engine cannot read or write either selected credential file through a broader directory grant. Each value is one path, not a list; a Unix filename may contain a literal :.

This does not forward arbitrary CLOUDSDK_* names, interpreter settings or external-account executable-enable flags, and does not extend gsutil/bq support. Native source admission and interpreter pinning are implemented.

Narrowing cannot silently remove selected CLOUDSDK_CONFIG, credential-file, active configuration (CLOUDSDK_ACTIVE_CONFIG_NAME), account (CLOUDSDK_CORE_ACCOUNT), impersonation (CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT), or declared project variables. Runtime refuses before native probes or execution. Unmapped gcloud commands also preserve GOOGLE_APPLICATION_CREDENTIALS or refuse its omission. The mapped GCP adapter deliberately excludes ADC and uses its selected native, credential_file or gke_metadata mode; see GCP sources.

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 ENGRT_* variable does nothing. After enrollment these config-key variables do not override the verified managed generation.

engrt

Variable Config key Default
ENGRT_NAME runtime.name engineering-runtime
ENGRT_LOG_LEVEL runtime.log_level info

authentication

Variable Config key Default
ENGRT_AUTHENTICATION_PROVIDER authentication.provider github
ENGRT_AUTHENTICATION_GITHUB_ENABLED authentication.github.enabled true
ENGRT_AUTHENTICATION_GITHUB_BASE_URL authentication.github.base_url https://api.github.com
ENGRT_AUTHENTICATION_GITHUB_TOKEN_ENV authentication.github.token_env ENGRT_GITHUB_TOKEN
ENGRT_AUTHENTICATION_GCP_ENABLED authentication.gcp.enabled false
ENGRT_AUTHENTICATION_GCP_BINARY authentication.gcp.binary gcloud
ENGRT_AUTHENTICATION_KUBERNETES_ENABLED authentication.kubernetes.enabled false
ENGRT_AUTHENTICATION_KUBERNETES_KUBECONFIG_PATH authentication.kubernetes.kubeconfig_path ""
ENGRT_AUTHENTICATION_OPENSHIFT_ENABLED authentication.openshift.enabled false
ENGRT_AUTHENTICATION_OPENSHIFT_BINARY authentication.openshift.binary oc
ENGRT_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
ENGRT_AUDIT_DELIVERY_MODE audit.delivery_mode local

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


Audit identity and correlation

ENGRT_CONSUMER

Sets the caller class: human, ci, or ai. When unset (v0.13.0), a non-empty CI selects ci; a known agent harness marker (CLAUDECODE, CODEX_THREAD_ID) selects ai with actor_source: detected_environment; otherwise the record says undeclared. Runtime never infers human — set it explicitly if that is who is calling.

ENGRT_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.

ENGRT_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 ENGRT_CONSUMER=ci
export ENGRT_ACTOR_NAME=production-release
export ENGRT_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; ENGRT_PORTAL_API_KEY is the separate secret credential kept out of configuration files.

Variable Config key Default
ENGRT_PORTAL_ENABLED portal.enabled false
ENGRT_PORTAL_BASE_URL portal.base_url ""
ENGRT_PORTAL_PATH_PREFIX portal.path_prefix /api/v1
ENGRT_PORTAL_TIMEOUT_SECONDS portal.timeout_seconds 5
export ENGRT_PORTAL_ENABLED=true
export ENGRT_PORTAL_BASE_URL=https://customer-control-plane.example
export ENGRT_PORTAL_PATH_PREFIX=/api/v1
export ENGRT_PORTAL_API_KEY='<show-once-runtime-key>'
engrt portal status

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

ENGRT_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

export ENGRT_HOME=/tmp/runtime-home
engrt bootstrap
export ENGRT_HOME="$PWD/runtime-home"
export ENGRT_CONSUMER=ci
export ENGRT_ACTOR_NAME=production-release
export ENGRT_SESSION_ID="$GITHUB_RUN_ID"
engrt config validate
export ENGRT_AUTHENTICATION_GITHUB_BASE_URL=https://ghe.example.com/api/v3
export ENGRT_GITHUB_TOKEN=ghp_xxx
engrt auth status

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