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; runtime 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. runtime 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:

runtime config init config --output ~/.config/engineering-runtime/config.yaml
runtime config init policy --output ~/.config/engineering-runtime/policy.yaml
export RUNTIME_CONFIG_FILE=~/.config/engineering-runtime/config.yaml
export RUNTIME_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

runtime 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 (`runtime context show`)
Capabilities: /Users/you/.engineering-runtime/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	$RUNTIME_HOME → $HOME/.engineering-runtime
Capability source	$RUNTIME_CAPABILITIES_DIR selects one authoritative directory; configured capabilities.sources add an ordered set; otherwise <home>/capabilities is the non-authoritative fallback
Config file	$RUNTIME_CONFIG_FILE → <home>/config.yaml
Policy file	$RUNTIME_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 (RUNTIME_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 RUNTIME_POLICY_FILE at a different file — a reviewable artifact — rather than exporting a variable that loosens a rule invisibly.

Editing configuration

Config and policy are hand-edited external documents. There is no runtime 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
runtime config validate      # confirm the change resolved as you intended

The runtime will not write its own configuration

runtime 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: runtime 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:
  RUNTIME_HOME: ${{ github.workspace }}/runtime-home
  RUNTIME_CONSUMER: ci
  # Set these only when the repository actually carries reviewed documents:
  # RUNTIME_CONFIG_FILE: ${{ github.workspace }}/.runtime/config.yaml
  # RUNTIME_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.9.8. After bootstrap, the version-exact files in Runtime Home win.