Skip to content

Configuration Overview

Engineering Runtime is configured by two documents you own, plus context that somebody else owns, plus the environment. Runtime creates none of them. A document Runtime writes is a document Runtime appears to own, and these are not its to own.

Your runtime carries its own contract

This site gets you installed, gets your first capabilities running, and explains how the pieces fit. Any Runtime command prepares the Home automatically; engrt bootstrap is the optional explicit report. Start at <Runtime Home>/RUNTIME-AGENT.md (the contract) and manifest.json (this binary's providers and operations). Specs and command cheatsheets for your installed version live in <Runtime Home>/specs/ and commands/. Read those for precise operational detail — they describe the binary you actually have. Come back here for concepts, upgrades, and anything not yet installed.

Document Governs Who owns it Reference
config.yaml Auth providers, base URLs, binary→auth-provider mapping, capability sources, optional control-plane client you config.yaml
policy-config.yaml What may execute at all you Policy
Context Where operations run — org, project, namespace kubectl, oc, gcloud, CI Where operations run

Both documents carry schema_version (absence means legacy v1). Config is v2; policy is v3 as of Runtime 0.9.1, which added command_policy.admitted_helpers. A v2 policy document is still read — the 2→3 migration is behaviour-preserving and rewrites nothing. The running binary publishes the version window and executable floor at <Runtime Home>/specs/schema-contract.json, with strict document shapes beside it in config-schema.json and policy-schema.json. In v0.9.9, bootstrap checks these installed bytes even when the version is unchanged. Use a successful authoring preflight's contract digests when reading a set across processes; do not consume a pending or mismatched generation. See Runtime Home recovery. engrt config migrate --surface config|policy --file <path> inspects a rewrite; --write applies it only outside the Runtime Home. Context has no Runtime schema — kubectl, oc, gcloud and CI own it.

Start from the compiled defaults, to a path you choose:

engrt config init config --output ~/.config/engineering-runtime/config.yaml
engrt config init policy --output ~/.config/engineering-runtime/policy.yaml
export ENGRT_CONFIG_FILE=~/.config/engineering-runtime/config.yaml
export ENGRT_POLICY_FILE=~/.config/engineering-runtime/policy.yaml

Neither is required. With no documents at all, the compiled default and the compiled safety profile are in force — a fresh install is governed, not ungoverned.

How a value is resolved

Exactly three layers, in this order, and no merging between them:

compiled default  <  one document you selected  <  one registered environment value

A document supplies the keys it actually sets; everything it does not mention keeps the compiled default. Collections replace whole — a sources list in your file is the entire list, not an addition to one.

Only keys listed in Environment Variables can be set from the environment. That is a closed list, not a rule: a key nobody registered is settable by nothing, which is deliberate — an ambient variable that can change governance is one anything in the process environment can change.

Plus environment variables for locations and credentials — see Environment Variables.

Everything above works with no server and no account. An optional control plane can publish policy to a fleet and collect audit records centrally; it is disabled by default and nothing on these pages depends on it.

Where they live

engrt config validate

The first lines of that report tell you exactly which files are active, including any relocated by environment variable:

Config:   compiled default
Policy:   compiled safety profile
Context:  owned by the tool that runs the operation (`engrt context show`)
Capabilities: /Users/you/.engrt/capabilities
Portal:   disabled (local policy only)

The Portal: line names the optional control plane when one is configured, and the published policy version last applied — a synced policy file is otherwise indistinguishable from one you edited yourself.

Precedence

Setting Resolution order
Runtime Home $ENGRT_HOME → $HOME/.engrt
Capability source $ENGRT_CAPABILITIES_DIR selects one authoritative directory; configured capabilities.sources add an ordered set; otherwise <home>/capabilities is the non-authoritative fallback
Config file $ENGRT_CONFIG_FILE → <home>/config.yaml
Policy file $ENGRT_POLICY_FILE → <home>/policy-config.yaml
A registered config key Its documented environment variable → the value in config.yaml → compiled default
A policy rule The policy file only — never an env var

Policy has no environment overrides

Only config keys with an explicitly registered environment variable can be overridden (ENGRT_AUTHENTICATION_GITHUB_BASE_URL, for example). Policy deliberately cannot be.

An environment variable must never be able to widen governance. If a pipeline needs different rules, it points ENGRT_POLICY_FILE at a different file — a reviewable artifact — rather than exporting a variable that loosens a rule invisibly.

Editing configuration

v0.9.9 config init evidence identifies the authority surface/class, not the supplied destination path. The command still returns its actual target. See stored audit privacy for what new records retain and what they intentionally omit.

Init, relocation and schema-write APIs now retain results alongside evidence errors. Init's byte count is what Write accepted, not a durability guarantee; its path names the requested destination. Relocation retains verified copies already made and stops before later steps; a schema write retains its observed post-digest. CLI failures show these details under an explicit failure rather than losing them. Inspect target/backup state before further writes. See incomplete evidence recovery.

Config and policy are hand-edited external documents. There is no engrt config set verb. Context is selected with the owning native tool, not a Runtime file or context create verb.

$EDITOR ~/.config/engineering-runtime/config.yaml
engrt config validate      # confirm the change resolved as you intended

The runtime will not write its own configuration

engrt files write is a real operation, but the File Engine refuses to read or write Runtime's selected config/policy, evidence or release-owned contracts, whether they are inside Home or elsewhere. Without that refusal a single command could rewrite policy and the next command would run under the new rules. Native credential stores are protected too; ordinary files are still bounded by file_policy grants.

There is exactly one sanctioned exception: engrt portal sync replaces policy-config.yaml with a control plane's published copy. It is opt-in, off by default, and — unlike the write the File Engine refuses — it is audited, so the change is never silent.

Configuration in CI

Pipelines usually ship their own config and policy rather than editing a home:

env:
  ENGRT_HOME: ${{ github.workspace }}/runtime-home
  ENGRT_CONSUMER: ci
  # Set these only when the repository actually carries reviewed documents:
  # ENGRT_CONFIG_FILE: ${{ github.workspace }}/.runtime/config.yaml
  # ENGRT_POLICY_FILE: ${{ github.workspace }}/.runtime/policy.yaml

See CI/CD for the full job contract.

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