Skip to content

Upgrading

Upgrading Engineering Runtime replaces the executable. There is no database or daemon to restart. The v0.10.0 naming change also requires updating scripts and environment variables and, if desired, explicitly copying or selecting the old Home as described below.

These instructions cover released v0.14.0. Follow Installation to obtain and verify the replacement archive. Complete any Home copy below before the first engrt command, then run:

engrt version
engrt bootstrap
engrt config validate

For the currently approved release, verify supported operating systems and architectures in the installation guide. User-owned governance is preserved in the selected Home. For rollback to an earlier release, use a separate Runtime Home and retain newer audit history; old/new evidence writers must not share one Home. See rollback limits.

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.

Upgrading from v0.13.0 to v0.14.0

The executable changes; config v2, policy v3, capability version: v1 and the Runtime Home remain compatible. Preserve a private backup of the existing Home and its evidence before upgrading. Follow the installation guide and keep any rollback binary on a separate Home.

  • Update automation that assumes a GitHub 404 proves a resource is absent. Curated observation steps now refuse that inference and stop dependent writes.
  • Inspect audit verify status and completeness, not only its exit code. Historical journals without an anchor can report CONSISTENT with unverified completeness (exit 9); a fresh Home reports NO_EVIDENCE (exit 8). These are different from a broken journal. Subsequent recording can anchor retained history; it cannot establish independent custody of rewritten history.
  • Repair malformed security configuration before execution. Its recorded collector-required obligation is not erased by configuration repair or a switch to local mode. Do not delete evidence to obtain a successful result.
  • Check scripts using native GitHub flags: additional spellings now receive the same compiled restrictions. Raw admission still includes only gh repo list.
  • Inspect partial repository-onboarding effects before retrying. The release does not claim completed end-to-end onboarding verification or automatic missing-resource repair.

See the v0.14.0 operations guide for the full audit exit table, supported recovery and qualification limitations.

Upgrading from v0.12.0 to v0.13.0

v0.13.0 keeps the engrt names, Runtime Home, config v2, policy v3 and version: v1 capabilities. Replace the binary (brew upgrade engineeringruntime/tap/engineering-runtime or the installer), then run engrt bootstrap and engrt config validate. Existing audit journals keep verifying, and a Home written by v0.12.0 works unchanged. engrt config validate now reports compiled-safety-profile/v4.

Check these before relying on the upgrade:

  • Destructive operations are refused whatever your policy says. Repository deletion, remote ref deletion, forced pushes, history rewriting, and removal of branch protection and rulesets are refused by the compiled safety profile on REST, GraphQL, command run git and gh, and inside capabilities, even under a policy that explicitly allows them. A script that did these through Runtime now fails with Refusal: compiled_safety (destructive-effect) and sends nothing; do them deliberately outside Runtime. The full list is in command run and the GitHub provider page.
  • Denial wording changed. "Policy denied" is now said only of a policy refusal. Scripts that match on the message should match Refusal: and the rule, or use the refusal object in --output json.
  • Malformed requests carry a refusal class (argument_invalid) while keeping status failure and exit 1.
  • Callers that declare nothing are undeclared, not human, in the audit record (set ENGRT_CONSUMER to label them).
  • engrt command run <binary> -- … is refused; put -- before the binary or omit it.
  • Repeated key=value fields are refused in GraphQL variables, file put fields and any REST body, instead of keeping the last value.
  • GitHub owner, repository and organization arguments that are not a single path segment (for example foo/../../notifications) are refused before authentication.
  • New: key:=<json> passes a nested JSON value into a REST body or GraphQL variable, and id-token: write is no longer hidden in dry-run diffs.

Upgrading from v0.11.0 to v0.12.0

v0.12.0 keeps the engrt names, Runtime Home, config v2, policy v3 and version: v1 capabilities. Replace the binary (brew upgrade engineeringruntime/tap/engineering-runtime or the installer), then run engrt bootstrap and engrt config validate. Existing audit journals keep verifying.

Check these before relying on the upgrade:

  • Raw gh no longer gets ENGRT's token. engrt command run gh and capability binary: gh steps use your own native gh login. Use engrt github … (provider: github) for work authorized through ENGRT.
  • New optional selectors. execution.surface and authentication.github.source (env, file, github_actions, github_app, os_secure_store) are optional; existing environment-token setups keep working. See GitHub setup.
  • macOS ENGRT session after an upgrade. The Keychain ties an ENGRT session to the binary that created it. If auth status reports auth_store_unavailable, remove the stale entry (security delete-generic-password -s engineering-runtime.github.v1; this does not touch gh) and run engrt auth login github again.
  • GCP interpreter. If auth status reports GCP auth_tool_incompatible, set authentication.gcp.python to an absolute Python 3.10–3.15 path, for example the interpreter shown by gcloud info.
  • Audit identity digests. New records carry identity_key_id; records from earlier releases remain readable but are not comparable with them.

Upgrading from v0.10.0 to v0.11.0

v0.11.0 keeps the engrt names, Runtime Home, config v2, policy v3 and version: v1 capabilities. Replace the binary, then run engrt bootstrap and engrt config validate. Existing audit journals keep verifying, and released v0.10.0 can still verify a journal that v0.11.0 has extended.

Review these behaviour changes before upgrading scripts and CI:

Change What to do
capability validate, plan and execute exit 0–4: 0 success, 1 failure after dispatch, 2 invalid, 3 refused before dispatch, 4 verification failed or unavailable Scripts that treated any non-zero exit as one failure keep working. Scripts that compared against exit 1 should accept 1–4. Direct operations and command run keep exit 0/1
A repeated --input key, or one without =, is refused as invalid_input (exit 2) Pass each input once; do not append defaults that rely on last-wins
An empty or whitespace-only policy rule entry refuses the policy at load Remove empty entries from allowed/denied and allowed_binaries/denied_binaries; engrt config validate names the list
HTTP results and declared-JSON command output refuse trailing data No action for well-formed JSON
A trailing --output is honoured after REST/GraphQL operations and in resolve Remove a trailing --output you did not intend; conflicting values refuse

Capabilities that declare engrt_version: ">=0.11.0" use the result grammar. v0.10.0 refuses them before any step runs, so a consumer that stays on v0.10.0 must pin a compatible capability catalog revision. Legacy capabilities keep their exact meaning and compiled invocation identity.

Upgrading from v0.9.x to v0.10.0

v0.10.0 renames Engineering Runtime's machine-facing names. There is no compatibility layer, so update scripts, shells and CI in the same change:

Before From v0.10.0
runtime binary engrt
engineering-runtime-<version>-<os>-<arch> archives engrt-<version>-<os>-<arch>
~/.engineering-runtime Runtime Home ~/.engrt
RUNTIME_* / ENGINEERING_RUNTIME_* variables ENGRT_* (for example ENGRT_HOME, ENGRT_POLICY_FILE, ENGRT_GITHUB_TOKEN)
RUNTIME_RUNTIME_NAME, RUNTIME_RUNTIME_LOG_LEVEL ENGRT_NAME, ENGRT_LOG_LEVEL
  • Old variable names are ignored, not refused. Unset them and export the ENGRT_* names; a leftover RUNTIME_POLICY_FILE no longer selects your policy.
  • ~/.engineering-runtime is not read by default. To keep its contracts and audit history, copy it to ~/.engrt before the first engrt command (recommended: the original stays as a rollback copy). Alternatively, point ENGRT_HOME at it; it then becomes the active Home and is upgraded in place, like any 0.9.x upgrade.
  • If your config.yaml sets authentication.github.token_env: RUNTIME_GITHUB_TOKEN, change it too (the default is now ENGRT_GITHUB_TOKEN).
  • RUNTIME_CONTEXT_FILE stays retired and still blocks execution; unset it. engrt context retire reports it when set. There is no ENGRT_CONTEXT_FILE.
  • Unless it is your active Home, ~/.engineering-runtime stays protected from File Engine reads and writes, so the previous audit history and keys are not exposed when you run engrt from $HOME.

Native variables keep their names and need no change: CI, GITHUB_ACTIONS, GITLAB_CI, KUBECONFIG, KUBERNETES_SERVICE_HOST, KUBERNETES_SERVICE_PORT, USER, USERNAME, and tool-contract variables such as CLOUDSDK_*. For gh, Runtime still grants the validated token as GH_TOKEN/GITHUB_TOKEN.

# find leftovers; this should print nothing after the upgrade
env | cut -d= -f1 | grep -E '^(ENGINEERING_)?RUNTIME_'

# keep previous local state (optional, before the first engrt command)
# stop all writers first; the destination must not already exist
test ! -e ~/.engrt && cp -Rp ~/.engineering-runtime ~/.engrt

engrt version
engrt bootstrap
engrt config validate

Even engrt version prepares Home. If ~/.engrt already exists, do not copy the old directory into it or overwrite it. Preserve both Homes and explicitly select the intended one with ENGRT_HOME.

In GitHub Actions a stored secret can keep its name:

env:
  ENGRT_HOME: ${{ github.workspace }}/engrt-home
  ENGRT_CONSUMER: ci
  ENGRT_GITHUB_TOKEN: ${{ secrets.RUNTIME_GITHUB_TOKEN }}

config diff policy is the shipped way to see allowed_binaries drift against this binary's compiled default — do not invent a throwaway Home to diff policy.

What changes and what survives

The next command you run after replacing the binary refreshes Runtime Home automatically: RUNTIME-AGENT.md, manifest.json, specs/ and commands/.

Path On upgrade
RUNTIME-AGENT.md, manifest.json, specs/, commands/ Replaced. Files the new version no longer ships are deleted from specs/ and commands/
version Updated to the new binary's version
config.yaml Never touched
policy-config.yaml Never touched
context.yaml Retired. If your Home still has one it now blocks every command — run engrt context retire, then move it out yourself
capabilities directory Never touched. Runtime ships no capabilities and adds none
logs/, cache/ Untouched

Upgrading an install from before 2026-08-11

Such a Home still holds the four documents Bootstrap used to seed. Nothing deletes, moves or rewrites them — but Runtime no longer owns that location, and one of them now needs a decision from you.

engrt config validate

reports them under Unowned state in Runtime Home, classified against every default this project has ever released:

Reported as What it means What to do
unmodified default … — safe to delete it matches this binary's compiled default deleting it preserves behaviour and lets the compiled default govern
unmodified default … — but not this binary's compiled default it is unchanged, but its release behaviour differs from 0.9.0 inspect engrt config validate / config diff policy; deleting it changes what governs
edited or unrecognised you changed it, or it came from a version we cannot recognise move it out — see below

An edited policy-config.yaml in the Runtime Home stops governing. Runtime will not guess whether you meant those rules to still apply from a location it has disclaimed, so it refuses and tells you the two ways out rather than picking one. Governed commands stop until you choose; engrt config validate keeps working, which is where the instructions are.

engrt config migrate-home --to ~/.config/engineering-runtime            # see the plan
engrt config migrate-home --to ~/.config/engineering-runtime --write    # copy it out
export ENGRT_POLICY_FILE=~/.config/engineering-runtime/policy-config.yaml

The write copies. Your original is never deleted, renamed or modified, an existing destination is never overwritten, and --to must already exist. The copy is read back and checked before Runtime says it worked. Or delete the file to run on the compiled safety profile.

A policy your Control Plane delivered with portal sync is not affected — that is an active delivery, not something left behind, and it keeps governing.

Context is not migrated at all: kubectl, oc and gcloud own it, so Runtime shows you the equivalent native command instead of copying it somewhere new.

Your policy edits, your context definitions and your capabilities survive every upgrade. That is the guarantee the ownership split exists to provide.

The first command consumes the refresh

Bootstrap runs before every command. If you run engrt version first, a subsequent engrt bootstrap prints no refresh line — the refresh already happened. That is success, not failure.

Schema migrations

Replacing the binary does not rewrite config.yaml or policy-config.yaml. Those files are yours. A newer Runtime can still read a supported older shape: it migrates in memory, leaves the bytes on disk alone, and executes against the migrated meaning.

That is different from config migrate-home, which copies a leftover file out of the Runtime Home. Schema migration is about the document's version, not its location.

# what this binary understands (generated, not hand-written)
cat ~/.engrt/specs/schema-contract.json

# inspect; the file is not touched
engrt config migrate --surface config --file ~/.config/engineering-runtime/config.yaml
engrt config migrate --surface policy --file ~/.config/engineering-runtime/policy.yaml

# apply only after the dry-run digest is the file you meant
engrt config migrate --surface policy --file ~/.config/engineering-runtime/policy.yaml \
  --write --expect-digest <digest-from-dry-run>
Outcome What Runtime does
Supported, behaviour-preserving Reads and executes; file bytes unchanged unless you pass --write
Meaning-changing or below the executable floor Explains why; governed execution blocks; the file is not rewritten
Newer than this binary, or older than the parse window Fails with the observed version and the supported range
--write without --expect-digest, or a digest mismatch Refuses; a race between dry-run and write must not silently rewrite a different file
Path inside the Runtime Home Refused — Home is not where you keep documents you edit

There is no auto_migrate, no write during bootstrap, and no network step. The binary never reads this website to decide a migration.

v0.9.9 retains config schema v2 and policy schema v3 — unchanged since v0.9.1, so upgrading needs no document edit. Config v1 migrates in memory without changing behaviour; v2 adds the local capabilities.authoring_source selector, which since v0.9.2 is optional: a single capabilities directory is authored into with no key set, and an existing selection still wins. Policy v3 adds command_policy.admitted_helpers; the v2→v3 migration is behaviour-preserving and rewrites nothing, so a v2 document is read unchanged. The policy v1→v2 migration removes the retired top-level enabled key: absent/true is behaviour-preserving and can run after an in-memory migration; false is meaning-changing and blocks until you remove it deliberately. The strict version-exact shapes are in specs/config-schema.json and specs/policy-schema.json.

The upgrade trap worth knowing

New policy defaults do not reach existing installs.

policy-config.yaml is user-owned, so a release that adds allowed_binaries entries or new deny rules changes nothing for anyone who already has the file. This has bitten real installs: a machine sat at 6 allowed binaries while the release shipped 21, and engrt command run helm was denied for what looked like no reason at all.

This is a deliberate trade — never clobbering your policy is worth more than auto-delivering defaults — but you have to know about it. The binary now surfaces the difference; it still will not rewrite the file.

Diagnose it

engrt config validate names the effective $ENGRT_POLICY_FILE and, when its allowed_binaries differ from this release, prints a count:

Policy:  /company/runtime/policy.yaml (explicit override (ENGRT_POLICY_FILE))
          info: allowed_binaries differs from runtime 0.9.1 defaults:
                15 release-default binaries absent; 0 policy-only binaries
                Run: engrt config diff policy

engrt config diff policy prints the full set — every release-default binary the effective policy omitted, and every policy-only binary this release does not ship. It is read-only. Version 1 compares allowed_binaries only.

engrt config validate
engrt config diff policy
engrt --output json config diff policy

A fresh Home with no ENGRT_POLICY_FILE runs the compiled default and prints no drift summary. A verified enterprise generation is reported as provenance and is never compared with vendor defaults.

Do not bootstrap a throwaway Home to recover the shipped YAML: Bootstrap no longer writes policy. Start from the compiled default with engrt config init policy --output … if you want a file to edit.

Verify the upgrade

engrt version
engrt config validate

# a capability that validated before must still validate
engrt capability validate files/notes-roundtrip

Validation resolves every step against the provider surface of the installed binary, so re-validating your capabilities after an upgrade is the fastest way to find an operation that changed or was removed.

If you keep capabilities in a checked-out source, validate all of them:

CAPABILITY_SOURCE=~/work/team-capabilities
for f in $(find "$CAPABILITY_SOURCE" -name '*.md'); do
  engrt capability validate "$f" || echo "FAILED: $f"
done

Downgrading

Downgrading works and is symmetric: specs/ and commands/ refresh back down to what the older binary ships, because the refresh triggers on any version difference, not just a newer one. Your user-owned files are untouched in that direction too.

The one thing to check is capabilities. A capability written against an operation that only exists in the newer binary will fail validation after a downgrade — which is exactly the intended behaviour, caught before execution rather than during it.

Upgrading in CI

Pin the checksum-verified binary version in your runner provisioning and update it deliberately. Use a fresh Runtime Home for each job. With no selected document, a fresh job uses the release's compiled defaults; an existing selected policy continues to govern until its owner changes it.

See CI/CD.

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