Engineering Runtime Documentation¶

Engineering Runtime is a single binary — runtime — that executes engineering operations deterministically, under policy, with an audit record for every outcome. Humans, CI/CD pipelines and AI agents all drive the same binary and get the same behaviour.

This site is the technical documentation: how to install it, configure it, authenticate it, and use every command it exposes.

Looking for the why?

Vision, architecture and the essay series live at www.engineeringruntime.com. This site stays deliberately operational — what to run, what to set, what to expect back.

Three ways to use it¶

Local (human)

Install the binary, bootstrap a Runtime Home, run provider operations and capabilities from your terminal.
CI/CD

Per-job Home, setup-runtime action, secrets, and capability execute in GitHub Actions (or any pipeline).
AI agent

Runtime Agent contract — Claude / Cursor may only call runtime, enforced by hooks.

Full map: Ways to use.

Start here¶

Installation

Download and verify a release on macOS, Linux or Windows.
Quick Start

Ten minutes from install to a governed, audited operation.
Authentication

The runtime validates credentials the platform already gave you.
CLI Reference

Every command, flag and output mode.

The execution lifecycle¶

Every operation — a provider call, a raw binary, a single step inside a capability — passes through the same six stages, in this order:

Bootstrap → Context → Policy → Authentication → Execution → Audit

Stage	What happens	Where it is configured
Bootstrap	Prepares the Runtime Home from assets embedded in the binary	`ENGINEERING_RUNTIME_HOME`
Context	Resolves where the operation runs — org, project, namespace	`context.yaml`
Policy	Allows or denies the operation before anything executes	`policy-config.yaml`
Authentication	Validates an existing platform credential	`config.yaml`
Execution	A Runtime Engine performs the work	—
Audit	Success, failure and denial are recorded	`<home>/logs/audit.log`

Policy runs before authentication on purpose: a denied operation never spends a credential round trip against the platform.

Two ways to execute¶

Provider operations — a curated surface. You name what you want; the provider decides how to reach the platform (REST, GraphQL, or a CLI):

runtime github repo list
runtime github repo view cli/cli
runtime files write ./notes.txt hello

The Command Engine — the escape hatch for tools no provider covers, gated by an allow-list of binaries and per-binary subcommand rules:

runtime command run terraform plan
runtime command run kubectl get pods

Both are governed identically. See Providers and command run.

Capabilities¶

A capability is a Markdown file with an embedded ```runtime block. It sequences operations into a reusable workflow that a human, a pipeline, or an AI can run identically:

```runtime
version: v1

inputs:
  path:
    description: Where to write the note
    required: true

workflow:
  - provider: files
    args: [write, "${path}", "hello"]

  - provider: files
    args: [read, "${path}"]
```

runtime capability validate my-first
runtime capability execute my-first --input path=./mine.txt

Read the Capability overview and the authoring reference.

Repository	Contents
`engineering-runtime-releases`	Versioned binaries, checksums, release notes
`engineering-runtime-capabilities`	Reusable capability library
`engineering-runtime-samples`	Working CI/CD workflows
`engineering-runtime-ai-agent`	Runtime Agent contract + shell hooks
Engineering Runtime site	Vision, architecture, essay series