Skip to content

Runtime Home

Released v0.14.0

GitHub, native-command and audit changes, recovery guidance and qualification limits are described in the v0.14.0 operations guide.

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

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/.engrt/
  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/               ┘ whenever version or asset contents differ
  .bootstrap.lock         persistent refresh/snapshot lock (v0.9.9)
  .bootstrap-pending.json complete staged assets while refresh is incomplete
  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 ENGRT_CONFIG_FILE at it
policy-config.yaml you, or your company anywhere you choose — point ENGRT_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 ENGRT_HOME=$(mktemp -d)
engrt bootstrap
engrt config validate | head -3        # "compiled safety profile"
engrt github api DELETE /repos/x/y     # still denied

Get a document to start from with engrt config init:

engrt config init policy --output ~/.config/engineering-runtime/policy.yaml
export ENGRT_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 engrt 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 ENGRT_HOME:

export ENGRT_HOME=/tmp/runtime-home
engrt bootstrap

Hardening status (v0.9.9)

The v0.9.9 Home and evidence protections support macOS and Linux. Windows is not supported in this release. Do not delete active operation directories, locks or keys to work around a problem — each section below says what to do instead.

Operation scratch safety (v0.9.9)

Native commands and standalone context probes run in private per-operation directories under cache/operations/. Standalone native auth checks use the same mechanism under a private per-user directory in the OS temporary root (.engineering-runtime-auth-<uid>). These are scratch space, not a credential store: native credential homes stay tool-owned, and tools whose credentials live in your real home keep using it.

Runtime removes a directory once its operation has finished. It never removes a directory that is still in use or whose state it cannot recognize — a dead Runtime process does not prove its child has stopped. Symlinks and replaced directories are refused rather than followed.

cache/operations, its lock and the auth scratch directory are protected from governed File Engine reads and writes, even under a broad grant. This is not a sandbox against a malicious native executable or the host owner.

If cleanup fails, the command returns operation_cleanup_failed while keeping its real output, exit code and effect classification (evidence_finalization_failed takes precedence if recording also failed). Under heavy contention allocation can refuse before the command starts.

  • Fix the underlying storage or permission problem.
  • Do not rerun a completed operation to clear scratch. A later run recovers finished, inactive directories automatically.
  • Remove a leftover directory yourself only after every process that might use it has stopped. engrt audit recover records evidence; it does not delete scratch or rerun commands.

Caller deadlines include preparation, not just native execution, so a short deadline can expire before the tool launches. See auth failure semantics for the auth-specific cases.

Bootstrap runs before everything

Runtime Home must be writable even for a diagnostic such as audit verify, because startup takes its maintenance lock. On a read-only filesystem, bootstrap, command execution and audit verification refuse before any native tool runs, so a read-only container root needs a separate writable Runtime Home mount.

When Home or its parent directories are missing, Runtime creates them privately and syncs each new directory. The parent must be readable and, on the same filesystem, support directory syncing. If that check fails, fix the parent's access or storage and retry — do not delete Home, its key or its evidence. Directories that already exist, and externally provisioned mounts, are left as they are.

For automation, select Runtime JSON before the binary or provider operation:

engrt --output json command run gcloud projects describe example-project --project=example-project
engrt github --output json repo list

Runtime v0.9.9 honors that selection even if bootstrap refuses: exit 1, one JSON object with status: failure, error_code: execution_rejected and the diagnostic error, no engine result and no duplicate stderr. No native tool launches after a bootstrap refusal. CLI/raw startup errors remain on stderr. Flags after the binary or provider operation are not Runtime output selectors.

Bootstrap is not something you have to remember. It runs before every command — version, audit tail, a provider operation, a capability step. engrt 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 engrt version first, a subsequent engrt 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 before comparison/publication — it is not fetched. Recomputing bytes does not mean rewriting an unchanged file.

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 engrt 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/ Refreshed when version or complete contents differ, including same-version drift. 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 pruned on refresh, even without a version bump. That is 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              $ENGRT_HOME, else $HOME/.engrt
2. Resolve capabilities dir  $ENGRT_CAPABILITIES_DIR, else <home>/capabilities
3. Bind Home and lock        .bootstrap.lock; ensure working directories
4. Build and compare         complete embedded/generated assets and version
5. If different/pending:     durably stage .bootstrap-pending.json;
                             publish files, prune, verify, sync version;
                             remove pending marker only after completion

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

Step 5 runs only when version or contents differ, or a pending marker exists. A policy edit or capability-source change cannot change the manifest's bytes.

The version marker

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

Comparison Result
Equal, complete assets also match, no pending marker No rewrite — bounded reads still verify the installed bytes
Equal, but assets missing/changed or refresh pending Refresh/repair from this binary
Different Refresh. Any difference, so a downgrade refreshes back down
Absent Refresh. Covers a brand-new home and a home created before version tracking

Repairing assets without a version change no longer requires deleting state:

engrt bootstrap

Interrupted refresh and concurrent readers

Refresh takes a cross-process lock (waiting at most 30 seconds) and stages the complete new asset set before changing installed files. Each file replacement is atomic, but the set as a whole is not one atomic step.

A crash or write failure leaves either the previous assets or .bootstrap-pending.json, which makes readers refuse the incomplete set. Fix the reported filesystem problem and run engrt bootstrap with the intended binary; recovery rebuilds from that binary. Do not remove the lock or the pending marker to bypass a refusal.

Asset entries that are symlinks, hard links or other non-regular files are refused, not followed or deleted. Inspect and move such an entry yourself. Installed asset trees are size-bounded (2,048 entries, 16 MiB total); exceeding that is an explicit refusal, not silent truncation.

engrt capability authoring-context reads a matched snapshot of the contracts for its own binary. If a different binary refreshes the same Home concurrently, it refuses with a clear mismatch instead of mixing versions. Use separate Homes for binaries of different versions that run at the same time.

Rolling back to 0.9.8 or earlier

Stop v0.9.9 and select a separate Runtime Home for the older binary. Keep the newer Home and its audit history intact, and select your external config and policy explicitly after checking the older binary supports their fields. Do not copy the newer evidence journal into the rollback Home or delete its keys or locks. A successful downgrade of specs/, commands/ and the version marker proves only that the contracts refreshed, not that the old binary can safely write the newer evidence format.

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.

Local audit privacy key (v0.9.9)

audit/privacy-key is Runtime's local correlation key, not a platform credential. audit/ must be private to its owner, and the key a private, single-link regular file. Symlinks, hard links, shared permissions and malformed keys refuse; Runtime never silently changes permissions or replaces a key.

An interrupted key creation is preserved and refused; a complete valid key is reused, never rotated. Do not delete the key or audit/.privacy-key.lock as a workaround. Investigate the storage or ownership problem and restore the key from a trusted backup if you have one. Creating a different key breaks correlation with earlier records and is an explicit operator decision.

Retained integrity and historical completeness

Local verification establishes integrity of retained frames. Without an external trusted terminal checkpoint, complete trailing-frame deletion cannot be detected. Such trailing-frame removal requires no recomputation of remaining hashes. Intact: true establishes internal consistency, not historical completeness. The local journal is tamper-evident, not tamper-proof. External checkpointing is post-v0.9.9 backlog work, not a release dependency or current feature.

Free-text detail is sanitized before it is recorded. If sanitization would alter a correlation identifier, the write refuses rather than unlinking evidence.

Stored audit privacy (v0.9.9)

New ordinary records and execution-evidence producers store operation classes, coarse policy outcomes and safe diagnostic classes, not raw argv, request bodies, probe selectors/output or engine error/success text. A failed provider resolution records only the provider class. File-edit audit outcomes keep ordered per-file statuses, counts and before/after digests; their path field is empty. Detailed results still go to the caller and should be handled as potentially private data.

Recognized secrets are guarded in decoded JSON before persistence and before the producer is wrapped in base64. Base64 is not encryption. Actor/session labels and capability source/name remain readable correlation/provenance fields; do not put secrets in them. The guard is not general DLP and cannot recognize every opaque secret, arbitrary encoding or private business value.

Historical records are never rewritten or retrospectively sanitized. Old sensitive records remain sensitive and need appropriate access control. Do not edit old history to make a refusal pass.

Each ordinary record is limited to 1 MiB and each evidence record to about 64 KiB. Oversized records refuse without being written or truncated. These are per-record limits, not a limit on total history.

Incomplete execution evidence (v0.9.9)

An operation result and its evidence can have different outcomes. Runtime v0.9.9 reports evidence_finalization_failed when recording fails, while preserving the observed result: native exit/streams, HTTP data and metadata, or the successful File operation. A simultaneous engine failure keeps its original category inside result.execution.error_code. A denied operation still reports no dispatch; an evidence error never changes it into an executed operation.

The ordinary audit log and the execution-evidence journal are written separately, not as one atomic transaction. A failed write before dispatch stops the operation from running. A failure after the operation ran proves neither that nothing was written nor that what was written is durable.

Stop operations using the affected Home, repair the reported storage problem, inspect the target through an authorized read, then use engrt audit status and engrt audit verify. Once no Runtime process still uses this Home, engrt audit recover records unresolved operation intents as outcome_unknown. A complete completion already present in the verified journal is not duplicated or replaced by unknown. Recovery never retries an operation or invents a missing capability aggregate completion. Preserve torn/corrupt bytes; do not trim a tail to force verification to pass. Keep the original caller result for reconciliation: recovered unknown evidence is not a contradiction of a success that the caller actually observed.

Portal registration/sync and local authority writes also return their observed results alongside recording failures. Do not repeat enrollment, copy, migration or logout just to obtain a successful audit record. Filesystem/lock safety, storage-fault coverage, scratch cleanup and journal bounds have separate sections.

Audit storage safety (v0.9.9)

Audit files and their locks must be single-link regular files with no group or other permissions. Runtime Home and logs/ must not be group- or other-writable (existing 0755 directories are accepted; new audit directories are created private). Symlinks, hard links, FIFOs, devices and shared permissions refuse without fallback. This does not protect against an administrator who controls the host.

Keep audit.log.lock and execution-evidence.jsonl.lock in place. Each lock wait is capped at 30 seconds. Removing a lock to force access can leave processes locking different files.

engrt audit verify exits 1 for broken or incomplete evidence, in both text and JSON. In JSON, inspect intact and truncated_final_line. A zero from audit status is diagnostic, not an integrity approval. A torn final record blocks further appends until it is investigated. Preserve damaged bytes; do not trim tails or rewrite old records to make verification pass. Recovery requires that no Runtime process is using the Home.

Platforms without the required file-descriptor protections fail closed.

Journal operating range (v0.9.9)

Audit reads stream the journal rather than loading it whole, and audit tail -n N keeps only the last N records. Each line is limited to 1 MiB. Commands that extract every record, or a very large tail, can exceed Runtime's 64 MiB working budget; they then fail explicitly without truncating the result or changing history, and a smaller tail still works.

The tested envelope for v0.9.9 is 200,000 evidence frames (about 198 MB). It is not a hard disk limit, but larger histories have not been tested. Verification time grows linearly with history — around 2–3 seconds at that size on a recent laptop.

  • There is no automatic rotation, deletion or history reset. Monitor available storage.
  • On a full disk, Runtime refuses new work and preserves existing assets and data. A command that completed before the disk filled keeps its real result and reports evidence_finalization_failed; recover as described in Incomplete execution evidence — never by rerunning it.
  • Free space outside Runtime evidence and credential stores. Never delete locks or history to force acceptance.

A larger or indefinite retention requirement needs a separately reviewed retention decision.

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
engrt capability list      # name, winning source, digest, summary, inputs
engrt --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 ENGRT_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 ENGRT_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 ENGRT_CAPABILITIES_DIR=/tmp/runtime-capability-source
engrt bootstrap
engrt 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

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

engrt 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.14.0. After bootstrap, the version-exact files in Runtime Home win.