Runtime Home¶

The Runtime Home is the directory holding Runtime-owned contracts and Runtime working state on a machine: the agent contract, the provider manifest, specs and cheatsheets that describe the installed binary, the audit log, and a cache. Configuration, policy, context and the authoritative capability library are owned elsewhere.

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; runtime 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.

Documentation is a product contract

Engineering Runtime documentation is an executable product contract for humans and agents: it exposes goals, inputs, commands, expected results and recovery. External tools and CI remain authoritative for effective context; provider platforms remain authoritative for credentials. Runtime resolves one safe context snapshot, applies policy, executes through the provider, and records that same snapshot in audit. Prose or model output cannot override those controls. File Engine, exact-executable and bounded-output limits are explicit; they are not a full host sandbox or universal DLP.

$HOME/.engineering-runtime/          # Windows: %USERPROFILE%\.engineering-runtime
  version                 the binary version this home was prepared by
  RUNTIME-AGENT.md        ┐ THE RUNTIME'S — the vendor-neutral entry point
  manifest.json           │ providers and operations of THIS binary
  specs/                  │ refreshed to match the binary
  commands/               ┘ on every version change
  logs/                   audit log and execution evidence
  cache/
  capabilities/           created, and empty on a fresh install (non-authoritative cache)
  audit/                  the audit privacy key (0600)
  enterprise/             signed governance, if a Control Plane delivered any
  trust/                  the keys that governance is verified against
  portal-policy-version   only if you use the optional control plane

Runtime creates no configuration, no policy and no context. That changed on 2026-08-11 and it is the single most important thing on this page: a document Runtime writes is a document Runtime appears to own, and these are not its to own.

Document	Who owns it	Where it lives
`config.yaml`	you, or your company	anywhere you choose — point `RUNTIME_CONFIG_FILE` at it
`policy-config.yaml`	you, or your company	anywhere you choose — point `RUNTIME_POLICY_FILE` at it
Context (project, cluster, namespace)	`kubectl`, `oc`, `gcloud`, or CI	wherever those tools keep it. Runtime observes it and never copies it
Capabilities	a source repository or catalog	wherever you keep them; list the directories in `capabilities.sources`
Enterprise policy and config	your Control Plane	`enterprise/`, written by Runtime and verified on every read. Not yours to edit

Nothing became ungoverned by this. With no policy document at all, the compiled safety profile is in force — a floor, not an off switch. Check it yourself:

export RUNTIME_HOME=$(mktemp -d)
runtime bootstrap
runtime config validate | head -3        # "compiled safety profile"
runtime github api DELETE /repos/x/y     # still denied

Get a document to start from with runtime config init:

runtime config init policy --output ~/.config/engineering-runtime/policy.yaml
export RUNTIME_POLICY_FILE=~/.config/engineering-runtime/policy.yaml

It writes the compiled default verbatim, refuses to overwrite anything, refuses a path inside the Runtime Home, and tells you the variable to set. There is no init context — the external tool owns that.

portal-policy-version is written by runtime portal sync and records which published policy this home is running. Bootstrap neither creates nor manages it, it never appears unless you enable the portal, and deleting it is harmless.

Relocate it entirely with RUNTIME_HOME:

export RUNTIME_HOME=/tmp/runtime-home
runtime bootstrap

Bootstrap runs before everything¶

Bootstrap is not something you have to remember. It runs before every command — version, audit tail, a provider operation, a capability step. runtime bootstrap exists only so you can see what it did; it never unlocks anything.

A practical consequence: the first command after replacing the binary consumes the refresh. If you run runtime version first, a subsequent runtime bootstrap prints no refresh line. That is success, not failure.

What ships inside the binary¶

The binary embeds configs/, specs/, commands/, capabilities/ and agent/RUNTIME-AGENT.md. A fresh machine needs the binary and nothing else: no network, no source checkout, no separate asset download. manifest.json is generated from the compiled provider registry on a version change — it is not fetched.

The two ownership classes¶

This distinction is the one to remember. Everything else about upgrades follows from it.

Class	Paths	Behaviour
User-owned	`config.yaml`, `policy-config.yaml`, the capabilities directory	Never created. With no document the compiled defaults are in force, and `runtime config validate` says which source that is. There is no `context.yaml`: where an operation runs comes from the tool that runs it. A Home `capabilities/` directory is a non-authoritative cache, not the library.
Runtime-owned	`RUNTIME-AGENT.md`, `manifest.json`, `specs/`, `commands/`	Rewritten to mirror the binary on a version change. Files the binary no longer ships are deleted from `specs/` and `commands/`.

The reasoning:

User-owned files are your configuration and your engineering knowledge. Destroying them on upgrade would make upgrading dangerous, so the runtime never touches them once they exist.
Runtime-owned files describe the binary. A capability spec or a command cheatsheet that disagrees with the installed binary is worse than none at all — it actively misleads both humans and AI. So they are made to match, every time.

Never keep your own files under specs/ or commands/

They will be deleted on the next version bump. That is by design, not a bug. Put your own material in the capabilities directory, or outside the Runtime Home entirely.

What Bootstrap does, in order¶

1. Resolve home              $RUNTIME_HOME, else $HOME/.engineering-runtime
2. Resolve capabilities dir  $RUNTIME_CAPABILITIES_DIR, else <home>/capabilities
3. Create directories        home, logs/, cache/, capabilities dir
4. Read <home>/version       "" when absent
5. If recorded != binary:    refresh specs/, commands/, RUNTIME-AGENT.md,
                             manifest.json and the schema contract; prune; record version

Nothing is seeded. An existing install keeps the documents a previous version wrote; detection and relocation are separate commands.

Step 5 is the only version-gated part. A policy edit or a capability-source change does not regenerate manifest.json.

The version marker¶

<home>/version holds the version of the binary that last prepared the home.

Comparison	Result
Equal to the running binary	No refresh — ordinary commands don't rewrite files
Different	Refresh. Any difference, so a downgrade refreshes back down
Absent	Refresh. Covers a brand-new home and a home created before version tracking

Forcing a refresh without a version change — the standard fix if you've edited specs/ or commands/ locally and want the shipped copies back:

rm ~/.engineering-runtime/version && runtime bootstrap

Pruning is confined¶

The refresh collects the files the binary ships for a tree, writes them all, then deletes anything else inside that tree's own directory. Pruning can never reach config.yaml, the capabilities directory, logs/, or anything else outside specs/ and commands/ — including unrelated files you have left in the Runtime Home.

Where capabilities come from¶

Runtime ships none and fetches none. An empty inventory on a fresh install is a complete answer, not a broken state.

Capabilities resolve from an ordered list of directories that already exist on the machine. The first source to provide a name wins, and Runtime tells you when another source also provided it — a capability silently overridden by a source you forgot about is the surprise this ordering creates.

schema_version: 2
capabilities:
  authoring_source: team
  sources:
    - name: mine
      dir: ~/work/my-capabilities
    - name: team
      dir: ~/work/team-capabilities

runtime capability list      # name, winning source, digest, summary, inputs
runtime --output json capability authoring-context

The digest is what makes "the same capability" checkable across two machines rather than a shared filename. A Home cache is labelled non-authoritative.

An empty list is success. Text output names capabilities.sources and RUNTIME_CAPABILITIES_DIR; JSON is a plain empty array.

<Runtime Home>/capabilities is searched last, so an install with no configuration keeps working exactly as it did. That unset fallback is the only non-authoritative cache: since 0.9.2, a directory you name in RUNTIME_CAPABILITIES_DIR is an ordinary authoritative source, reported as capabilities-dir, because you chose it.

That same directory is where new capabilities are written. With one directory configured there is nothing else to set. authoring_source remains available to name one of several configured sources, and still wins when set — Runtime never silently picks the first. The target must exist and be writable; it does not need a file_policy.write_roots grant, because those roots govern the File Engine acting on your behalf rather than you editing a file with your own tools.

export RUNTIME_CAPABILITIES_DIR=/tmp/runtime-capability-cache
runtime bootstrap
runtime capability list

When the override is set, no capabilities/ directory is created inside the Runtime Home at all. See Sharing a Capability Directory.

Inspecting a home¶

runtime bootstrap --output json     # paths, version transition, refreshed/pruned files
runtime config validate             # resolved locations + live auth and binary checks
ls -R "${RUNTIME_HOME:-$HOME/.engineering-runtime}"

runtime bootstrap --output json reports the home and capabilities paths, whether the home was just created, the version transition, and exactly which files were refreshed and pruned on that run.

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