Configuration Overview¶

Engineering Runtime is configured by three files plus the environment. All three are user-owned: seeded once into the Runtime Home and never overwritten, not even by an upgrade.

File	Governs	Reference
`config.yaml`	Auth providers, base URLs, binary→auth-provider mapping	config.yaml
`policy-config.yaml`	What may execute at all	Policy
`context.yaml`	Where operations run — org, project, namespace	Runtime Context

Plus environment variables for locations, credentials and per-key overrides — see Environment Variables.

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:   /Users/you/.engineering-runtime/config.yaml
Policy:   /Users/you/.engineering-runtime/policy-config.yaml
Context:  /Users/you/.engineering-runtime/context.yaml (active: default)
Capabilities: /Users/you/.engineering-runtime/capabilities

Precedence¶

Setting	Resolution order
Runtime Home	`$ENGINEERING_RUNTIME_HOME` → `$HOME/.engineering-runtime`
Capabilities dir	`$RUNTIME_CAPABILITIES_DIR` → `<home>/capabilities`
Config file	`$RUNTIME_CONFIG_FILE` → `<home>/config.yaml`
Policy file	`$RUNTIME_POLICY_FILE` → `<home>/policy-config.yaml`
A config key	`RUNTIME_<KEY>` env var → the value in `config.yaml`
A policy rule	The policy file only — never an env var

Policy has no environment overrides¶

Any key in config.yaml can be overridden by an environment variable (RUNTIME_AUTHENTICATION_GITHUB_BASE_URL, and so on). 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¶

All three files are hand-edited. There is no runtime config set verb, and no context create verb — the files are the interface, which is what makes them reviewable in version control.

$EDITOR ~/.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 write config.yaml, policy-config.yaml, context.yaml, version, specs/ or commands/ inside the Runtime Home. Without that refusal a single command could rewrite policy and the next command would run under the new rules. Reads are unaffected, and everything outside those paths stays writable.

Configuration in CI¶

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

env:
  ENGINEERING_RUNTIME_HOME: ${{ github.workspace }}/runtime-home
  RUNTIME_CONFIG_FILE:      ${{ github.workspace }}/runtime-home/config.yaml
  RUNTIME_POLICY_FILE:      ${{ github.workspace }}/runtime-home/policy-config.yaml
  ENGINEERING_RUNTIME_CONSUMER: ci
  RUNTIME_GITHUB_TOKEN:     ${{ secrets.RUNTIME_GITHUB_TOKEN }}

See CI/CD for the full job contract.