`config.yaml`¶

Runtime identity, Auth Engine providers, the binary→auth-provider map, and the optional control-plane client.

Recommended location: a path you own outside Runtime Home, selected with $RUNTIME_CONFIG_FILE. <Runtime Home>/config.yaml is the legacy fallback. Runtime never creates or overwrites it — get one with runtime config init config --output <path>, then set RUNTIME_CONFIG_FILE.

Schema version¶

Documents carry an integer schema_version. Absence means version 1 — a file written before versioning existed is legacy, not invalid. Config is now v2; v1 remains readable and keeps its previous behaviour. This binary publishes the current version, read window and executable floor at <Runtime Home>/specs/schema-contract.json, and the strict machine-readable shape at <Runtime Home>/specs/config-schema.json.

A misspelled key is an error that names the key and line. It is never silently ignored as "use the default".

Unknown, duplicate, type-invalid and trailing YAML documents fail the same way in every consumer: execute, config validate, status, migration.

runtime config migrate --surface config --file ~/.config/engineering-runtime/config.yaml

Dry-run is the default. --write rewrites the file only after --expect-digest matches the bytes the dry-run showed, and never inside the Runtime Home. See Upgrading.

Complete example¶

Bootstrap does not create this file. Generate a reference outside Runtime Home with runtime config init config --output <path>, or start from this example and select it with RUNTIME_CONFIG_FILE.

schema_version: 2

runtime:
  name: engineering-runtime
  log_level: info

# Optional control plane. Disabled by default — the runtime never contacts
# a portal unless you turn this on.
portal:
  enabled: false
  base_url: ""                 # company Control Plane origin
  path_prefix: /api/v1         # only authenticated Runtime surface
  timeout_seconds: 5

# Auth Engine configuration. Engineering Runtime never replaces platform
# authentication; it only validates credentials that already exist on the
# machine, using each platform's own tooling.
authentication:
  provider: github

  github:
    enabled: true
    base_url: https://api.github.com
    token_env: RUNTIME_GITHUB_TOKEN

  gcp:
    enabled: false
    binary: gcloud

  kubernetes:
    enabled: false
    kubeconfig_path: ""     # defaults to $KUBECONFIG or ~/.kube/config

  openshift:
    enabled: false
    binary: oc
    server: ""

# Maps a `runtime command run <binary>` binary to the Auth Engine provider
# it validates against before executing.
command_providers:
  gh: github
  gcloud: gcp
  gsutil: gcp
  bq: gcp
  kubectl: kubernetes
  oc: openshift
  helm: kubernetes
  flux: kubernetes
  istioctl: kubernetes

# Ordered authoritative directories. Empty is a valid fresh state.
capabilities:
  # Optional local authoring target. Must name exactly one source below.
  # authoring_source: team-worktree
  sources: []

audit:
  delivery_mode: local

Key reference¶

`schema_version`¶

Key	Type	Default	Meaning
`schema_version`	int	`1` when absent	Document schema. Current is `2`; current plus two prior versions are readable, while a separate executable floor can refuse an old shape without making it unreadable

`runtime`¶

Key	Type	Default	Meaning
`runtime.name`	string	`engineering-runtime`	Display/logical name of this runtime instance
`runtime.log_level`	string	`info`	Verbosity: `debug`, `info`, `warn`, `error`

`audit`¶

What happens to execution evidence. Default is local-only: frames are finished the moment they are written, and no collector backlog accrues.

Key	Type	Default	Meaning
`audit.delivery_mode`	`local` \| `collector-required`	`local`	`local` stamps `delivery_not_required`. `collector-required` keeps evidence pending until the Control Plane acknowledges the exact bytes. An enterprise generation that requires collection is a floor: local config and `RUNTIME_AUDIT_DELIVERY_MODE` cannot lower it

`capabilities`¶

Ordered, authoritative directories of capability definitions, plus an optional single local worktree selected for authoring. Runtime searches sources in order and reports the winning source and content digest. It does not fetch a branch or infer a repository revision; pin the checkout yourself and include that revision in the source name.

capabilities:
  authoring_source: team-capabilities@<reviewed-commit>
  sources:
    - name: team-capabilities@<reviewed-commit>
      dir: /absolute/path/to/team-capabilities

authoring_source is optional as of 0.9.2. With a single capabilities directory — whether from RUNTIME_CAPABILITIES_DIR or one sources entry — Runtime authors there with no key set. Name one only when several are configured, where Runtime asks rather than guessing.

When set, it must match exactly one source name, or the literal capabilities-dir for the directory named by RUNTIME_CAPABILITIES_DIR. Its directory must be absolute. Duplicate names, an unknown name, surrounding whitespace, or a relative selected directory fail config validation. A selected directory that does not yet exist is valid configuration but reports authoring as not ready. Selection does not grant the File Engine access to the directory. That is separate from authoring: you edit capability source with your own tools, so no file_policy.write_roots grant is required unless a capability workflow itself will write there through provider: files.

Inspect the resulting contract without authenticating or executing anything:

runtime --output json capability authoring-context

The report names the installed specs and digests, selected source, policy provenance, provider surface, allowed binaries and exact readiness reason.

The directory named by RUNTIME_CAPABILITIES_DIR is an authoritative source. Only the unset <Runtime Home>/capabilities fallback is searched last as a non-authoritative compatibility cache and never selected for managed authoring.

`portal`¶

Optional control-plane client, off by default.

Key	Type	Default	Meaning
`portal.enabled`	bool	`false`	Whether Enterprise registration/sync/heartbeat is enabled. When false, no Control Plane request is made
`portal.base_url`	string	`""`	Control-plane API origin, no trailing slash. Empty disables the client even when `enabled: true`
`portal.path_prefix`	string	`/api/v1`	Fixed authenticated Runtime API prefix; other values are rejected
`portal.timeout_seconds`	int	`5`	Bounds registration, manual sync, and heartbeat calls

Leaving it disabled costs you nothing — policy, audit and every command work identically. Successful runtime portal register is the sticky authority transition: later local config/policy sources cannot override the verified managed generation. See Control Plane (Portal).

`authentication`¶

Key	Type	Default	Meaning
`authentication.provider`	string	`github`	Fallback Auth Engine provider when nothing else declares one. A Runtime Provider normally declares its own

`authentication.github`¶

Key	Type	Default	Meaning
`enabled`	bool	`true`	Whether the GitHub auth provider participates
`base_url`	string	`https://api.github.com`	REST API base URL. Change for GitHub Enterprise Server
`token_env`	string	`RUNTIME_GITHUB_TOKEN`	Name of the env var holding the token — never the token itself

`authentication.gcp`¶

Key	Type	Default	Meaning
`enabled`	bool	`false`	Enable once `gcloud auth application-default login` has been run
`binary`	string	`gcloud`	Binary name or path used for ADC validation

`authentication.kubernetes`¶

Key	Type	Default	Meaning
`enabled`	bool	`false`	Whether the Kubernetes auth provider participates
`kubeconfig_path`	string	`""`	Explicit kubeconfig path. When empty, falls back to `$KUBECONFIG`, then `~/.kube/config`

Validation reads the kubeconfig's current context directly — no kubectl binary required.

`authentication.openshift`¶

Key	Type	Default	Meaning
`enabled`	bool	`false`	Enable once `oc login` has been run
`binary`	string	`oc`	Binary name or path used for `oc whoami` validation
`server`	string	`""`	Optional API server hint. Login itself still happens with `oc login`, outside the runtime

`command_providers`¶

Maps a runtime command run <binary> binary to the Auth Engine provider it should validate against before executing.

A binary with no entry here skips the Auth Engine entirely — it is assumed to manage its own credentials (Terraform's provider blocks, Docker's registry logins, Vault's own token). That is a deliberate design decision, not a gap.

command_providers:
  gh: github
  terraform: none      # explicit "no auth provider" is also valid

helm, flux and istioctl all map to kubernetes because they read the same active kubeconfig context kubectl does, and the Kubernetes auth provider validates that file directly.

command_providers is not a Runtime Provider list

These are Auth Engine providers — credential sources. A Runtime Provider (github, files) is an operation surface, and lives in the binary, not in this file. See Providers.

Never put tokens in this file¶

config.yaml stores the name of an environment variable, not its value:

token_env: RUNTIME_GITHUB_TOKEN     # correct

Change the name if a pipeline already exports a differently named token:

export RUNTIME_AUTHENTICATION_GITHUB_TOKEN_ENV=MY_EXISTING_PAT
export MY_EXISTING_PAT=ghp_xxx

Environment overrides¶

Only keys explicitly registered with an environment variable can be overridden. The environment wins over the file for those keys. Collection values such as capabilities.sources and command_providers have no inferred environment form; edit the selected file instead.

export RUNTIME_AUTHENTICATION_GITHUB_BASE_URL=https://ghe.example.com/api/v3
export RUNTIME_AUTHENTICATION_GCP_ENABLED=true
export RUNTIME_RUNTIME_LOG_LEVEL=debug

The variable surface is closed: a plausible RUNTIME_<KEY> name that is not in the registry does nothing. Full list: Environment Variables.

GitHub Enterprise Server¶

authentication:
  github:
    enabled: true
    base_url: https://ghe.example.com/api/v3
    token_env: RUNTIME_GITHUB_TOKEN

Or without editing the file at all:

export RUNTIME_AUTHENTICATION_GITHUB_BASE_URL=https://ghe.example.com/api/v3
export RUNTIME_GITHUB_TOKEN=ghp_xxx
runtime auth status

The REST and GraphQL Engines verify that an assembled URL still points at the configured base URL's scheme and host, so a crafted path cannot redirect your bearer token to another host.

Verify a change¶

runtime config validate

The report shows every auth provider's enabled state, whether its CLI binary is installed, and its live auth status — so a wrong base_url or a missing token shows up as a failed check rather than as a confusing error mid-operation.

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

config.yaml¶

Schema version¶

Complete example¶

Key reference¶

schema_version¶

runtime¶

audit¶

capabilities¶

portal¶

authentication¶

authentication.github¶

authentication.gcp¶

authentication.kubernetes¶

authentication.openshift¶

command_providers¶