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:
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 verifystatus and completeness, not only its exit code. Historical journals without an anchor can reportCONSISTENTwith unverified completeness (exit 9); a fresh Home reportsNO_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 gitandgh, and inside capabilities, even under a policy that explicitly allows them. A script that did these through Runtime now fails withRefusal: compiled_safety (destructive-effect)and sends nothing; do them deliberately outside Runtime. The full list is incommand runand 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 therefusalobject in--output json. - Malformed requests carry a refusal class (
argument_invalid) while keeping statusfailureand exit1. - Callers that declare nothing are
undeclared, nothuman, in the audit record (setENGRT_CONSUMERto label them). engrt command run <binary> -- …is refused; put--before the binary or omit it.- Repeated
key=valuefields are refused in GraphQL variables,file putfields 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, andid-token: writeis 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
ghno longer gets ENGRT's token.engrt command run ghand capabilitybinary: ghsteps use your own nativeghlogin. Useengrt github …(provider: github) for work authorized through ENGRT. - New optional selectors.
execution.surfaceandauthentication.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 statusreportsauth_store_unavailable, remove the stale entry (security delete-generic-password -s engineering-runtime.github.v1; this does not touchgh) and runengrt auth login githubagain. - GCP interpreter. If
auth statusreports GCPauth_tool_incompatible, setauthentication.gcp.pythonto an absolute Python 3.10–3.15 path, for example the interpreter shown bygcloud 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 leftoverRUNTIME_POLICY_FILEno longer selects your policy. ~/.engineering-runtimeis not read by default. To keep its contracts and audit history, copy it to~/.engrtbefore the firstengrtcommand (recommended: the original stays as a rollback copy). Alternatively, pointENGRT_HOMEat it; it then becomes the active Home and is upgraded in place, like any 0.9.x upgrade.- If your
config.yamlsetsauthentication.github.token_env: RUNTIME_GITHUB_TOKEN, change it too (the default is nowENGRT_GITHUB_TOKEN). RUNTIME_CONTEXT_FILEstays retired and still blocks execution; unset it.engrt context retirereports it when set. There is noENGRT_CONTEXT_FILE.- Unless it is your active Home,
~/.engineering-runtimestays protected from File Engine reads and writes, so the previous audit history and keys are not exposed when you runengrtfrom$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.
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.
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.