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
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.
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.
ENGRT_POLICY_FILE¶
Absolute path to a policy-config.yaml outside the Runtime Home.
It is rejected after Enterprise enrollment.
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.
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:
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.
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.
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:
Recipes¶
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.