Where operations run¶

Goal: understand where Runtime sends an operation, change it, and clear a retired context.yaml if you are upgrading from an older install.

Runtime keeps no context of its own. The tool that runs an operation decides where it goes — kubectl and oc read your kubeconfig, gcloud reads its own configuration, and admitted gh modes read gh's host/account configuration. An explicit selector on the invocation always wins.

context.yaml is retired and now blocks

Runtime used to keep a context.yaml in the Runtime Home holding an org, project, cluster and namespace. If your Home still has one, every governed command stops until you move it out. That is deliberate: a file that is read but not obeyed would let you believe operations go one place while they go another. Jump to Clearing a retired context.yaml.

Prerequisites¶

Runtime installed. The first command prepares Runtime Home automatically; runtime bootstrap is an optional explicit report.
For Kubernetes/OpenShift targets: a kubeconfig, i.e. kubectl already works.
For GCP targets: gcloud installed and pointed at a project.

How a target is decided¶

Two sources, in order. There is no third.

Selectors on the command. --namespace, --context, --project — these are authoritative for that one invocation.
The tool's own state. Your kubeconfig's current-context, gcloud's configured project.

Nothing is guessed. If a value cannot be resolved and the operation needs one, the operation is refused rather than sent somewhere plausible.

Steps: see where you are pointed¶

runtime context show

Expected output (from a machine with gcloud configured and no kubeconfig):

kubectl (kubernetes)
  binding:   selector_bound
  learned:   parser
  unresolved: context
  set it with: kubectl config use-context <name>  ·  kubectl config set-context --current --namespace <ns>
oc (kubernetes)
  binding:   selector_bound
  learned:   parser
  unresolved: context
  set it with: oc project <name>
gcloud (gcp)
  binding:   selector_bound
  learned:   reserved_cli_probe
  project:   engineering-runtime-saas
  set it with: gcloud config set project <id>

runtime context show --output json gives the same thing as stable JSON. It contains no credentials.

Three fields are worth reading closely.

learned says how Runtime found out.

Value	Meaning
`parser`	Runtime opened and parsed a documented file (your kubeconfig). No process ran.
`reserved_cli_probe`	Runtime asked the tool, after recording a `context_probe` intent in the audit journal first.
`unavailable`	A probe was the only way to answer and Runtime could not record one, so the value is left unresolved.
`none`	Nothing needed reading.

Asking gcloud is treated as an effect, not a free read: gcloud config get-value project may write logs and configuration state while answering. That is why it is recorded before it happens.

binding says how firmly the target is held, and it decides what may run.

Binding	Meaning	Can back a change?
`strong`	every value is pinned; the tool cannot re-interpret it	yes
`selector_bound`	Runtime pinned a name, and the tool resolves that name itself against a file it re-reads	no
`context_free`	the operation does not depend on where it runs	yes

Read-only today for kubectl, oc and gcloud

No adapter can claim strong yet, so reads are allowed and changes are refused for context-aware tools. kubectl get pods runs; kubectl delete ns prod is refused with an explanation. The reason is not caution for its own sake: Runtime approved "delete in namespace staging", and kubectl would then go and look up what staging means in a file that may have changed since. Reading from the wrong place shows up in the output; changing the wrong place does not.

unresolved lists what could not be determined. A read that does not need the value still works.

Steps: change where operations go¶

Use the tool that owns the answer. Runtime never runs these for you — selecting a context is that tool's operation, not Runtime's.

kubectl config use-context staging
kubectl config set-context --current --namespace orders
oc project staging
gcloud config set project acme-staging

Or name it on the command, which wins for that invocation and is the only form that shows up explicitly in the audit record:

runtime command run kubectl --namespace orders get pods
runtime command run gcloud --project=acme-staging compute instances list

Passing the same selector twice with different values is refused rather than resolved — Runtime will not choose between --context a and --context b.

GitHub provider operations take an organization as an argument¶

GitHub has no native context for Runtime to read: there is no equivalent of a current kubeconfig context. So the organization is an argument.

runtime github repo list              # your own repositories
runtime github repo list acme         # an organization's
runtime github issue list acme
runtime github team list acme

issue list and team list require it. Capabilities that touch an organization declare it as a required input:

runtime capability execute github/github-org-health-check --input organization=acme

This replaced a fallback that read the org from context.yaml. That fallback made the same command mean one organization on a laptop and another in CI, with nothing on the command line to show which.

The direct native mode runtime command run gh repo list [OWNER] follows gh's own behaviour. An explicit owner is authoritative. Without one, gh uses the authenticated account on GH_HOST (default github.com). Runtime records that as a selector-bound github_account context and starts gh in a private working directory, so it cannot infer a repository from the checkout where you invoked Runtime.

Which tools are context-aware¶

Every tool is registered as one of three things, and an unregistered tool is treated as unsupported rather than assumed safe.

Mode	Tools
Context-aware — Runtime observes native state	`kubectl`, `oc`, `gcloud`, `gsutil`, `bq`, `helm`, `flux`, `istioctl`; `gh.repo.list` semantic mode
Context-free — coordinates come from arguments or a project file	`git`, `terraform`, `pulumi`, `packer`, `kustomize`, `docker`, `podman`, `sops`, `vault`, `argocd`
Unsupported through `command run`	every other direct `gh` mode; `aws`, `az`

The unsupported modes select targets from ambient state Runtime cannot safely bind — many gh modes take a repository from the working directory, aws picks an account through its credential chain, and az keeps an active subscription. Runtime will not approve an operation it cannot locate. Admission is per semantic mode, so support for gh.repo.list does not grant the rest of gh.

Clearing a retired `context.yaml`¶

If your Runtime Home still has one, commands stop with this:

runtime context: /Users/you/.engineering-runtime/context.yaml is a retired Runtime context document, and it is not in force.

Runtime no longer keeps its own context: the tool that runs the operation decides where it goes. Leaving this file readable but ignored would let you believe operations go one place while they go another, so it blocks instead.

Run this to see what each value maps to:
  runtime context retire

Then move the file out of Runtime's way yourself:
  mv /Users/you/.engineering-runtime/context.yaml /Users/you/.engineering-runtime/context.yaml.retired

Run the diagnostic. It is a dry run and changes nothing:

runtime context retire

Expected output:

Retired context document: /Users/you/.engineering-runtime/context.yaml

Runtime no longer keeps its own context. Here is where each value lives now:

  prod.kubernetes.context = prod-cluster
    owned by kubectl
    kubectl config use-context prod-cluster
  prod.kubernetes.namespace = orders
    owned by kubectl
    kubectl config set-context --current --namespace orders
  prod.cloud.project = acme-prod
    owned by gcloud
    gcloud config set project acme-prod
  prod.github.organization = acme
    GitHub has no native context. Pass the organization explicitly on the operation, or as a capability input
  prod.environment = production
    Runtime invented this field; no tool owns it. If it selected behaviour, that belongs in your policy document or the capability's inputs

Runtime will not move, rename or delete this file. Do it yourself:
  mv /Users/you/.engineering-runtime/context.yaml /Users/you/.engineering-runtime/context.yaml.retired

Governed execution stays blocked until it is outside the Runtime Home.

Then, in order:

Set each value with the native command the diagnostic printed.
Add organization (and any other invented field's replacement) to the commands or capability inputs that need it.
Move the file yourself. Runtime never moves, renames or deletes it — a runtime that tidies away governance documents is one you cannot audit.

runtime config validate keeps working the whole time, so you can diagnose while execution is blocked.

RUNTIME_CONTEXT_FILE is retired the same way. If it is exported, unset it; it selects a document that no longer exists as a concept.

Common failures¶

Message	Cause	Fix
`is a retired Runtime context document`	`context.yaml` in the Runtime Home	Run `runtime context retire`, then move the file
`RUNTIME_CONTEXT_FILE is set`	the retired override is exported	`unset RUNTIME_CONTEXT_FILE`
`needs a resolved target and none is bound`	the tool has no current context and none was passed	`kubectl config use-context <name>`, or pass `--context`/`--namespace`
`resolved its target as selector_bound … changes are not`	a change through a context-aware tool	Expected today — reads are allowed, changes are not. Use the tool directly if you accept the risk
`is registered as context-unsupported`	an unadmitted gh mode, `aws` or `az` through `command run`	Use `runtime github ...` for GitHub or the admitted `gh repo list`; AWS and Azure have no supported direct path yet
`needs an organization`	`issue list` / `team list` with no org	Pass it: `runtime github issue list acme`
`was given more than once with different values`	a repeated conflicting selector	Pass it once

Exit codes¶

0 on success. Any refusal above exits non-zero and is written to the audit log as a denial or failure — including the ones that never reached the platform.

Checking without executing¶

runtime resolve context show
runtime resolve context retire

runtime resolve confirms a command line resolves to something real, with zero side effects — no auth, no policy evaluation, no execution.

Next¶

Configure providers

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