Run Your First Capability

Goal: bootstrap a clean Home, see that an empty capability list is success, run an auth-free files capability, and read the audit record.

No GitHub account, tenant, Control Plane, or private repository. This is the minimal local path. GitHub is a separate follow-up.

Already need to install? See Installation.

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.

1. Bootstrap

runtime bootstrap

Expected output on a first run (default Home path shown as ~):

Runtime Home: ~/.engineering-runtime
  created runtime home
Capabilities: ~/.engineering-runtime/capabilities
  refreshed runtime-owned specs/ and commands/ for (new runtime home) -> <version>: 39 file(s) written
Runtime is ready.

If the directory already existed you get runtime home already existed instead of created runtime home. Both are success. Runtime writes no config.yaml, no policy-config.yaml, no context.yaml, and no example capabilities. The capabilities/ directory is created empty.

runtime version
# runtime 0.9.1

See Runtime Home for the layout.

2. Confirm the empty inventory

runtime capability list

No capabilities resolved.

That is a valid state, not a broken one — Runtime ships none and fetches nothing. Configure capabilities.sources for named resolution, or execute a reviewed file by exact path. RUNTIME_CAPABILITIES_DIR only relocates the non-authoritative compatibility cache.

JSON is a plain empty array:

runtime --output json capability list
# {"capabilities":[]}

3. Run an auth-free files capability

Compiled policy grants the working directory (.) for file reads and writes. Download the public fixture at an immutable source revision, then work in a disposable directory:

CAPABILITY_REVISION=daf5d4bdd20115f60e7463b77552510445b6097f
FIXTURE_DIR="$(mktemp -d)"
curl -fsSL \
  "https://raw.githubusercontent.com/engineeringruntime/engineering-runtime-capabilities/${CAPABILITY_REVISION}/capabilities/files/notes-roundtrip.md" \
  -o "${FIXTURE_DIR}/notes-roundtrip.md"

# Expected SHA-256:
# b3dfdaa09902d525608d5e3f2770b971a45ee1b948ed4fad9bb67587488c1680
shasum -a 256 "${FIXTURE_DIR}/notes-roundtrip.md"

WORK_DIR="$(mktemp -d)"
cd "${WORK_DIR}"

CONFIG_CONTENT=$'schema_version: 1\ncapabilities:\n  sources:\n    - name: public-reference@'"${CAPABILITY_REVISION}"$'\n      dir: '"${FIXTURE_DIR}"
runtime files write ./runtime-source.yaml "${CONFIG_CONTENT}"
export RUNTIME_CONFIG_FILE="${WORK_DIR}/runtime-source.yaml"

runtime capability list
runtime --output json capability list
runtime capability validate notes-roundtrip
runtime capability execute notes-roundtrip \
  --input path=./notes.txt --input message=hello

The list reports notes-roundtrip from public-reference@<revision> with digest b3dfdaa09902…; JSON includes "authoritative": true. The revision plus full file digest identifies the exact public content used. Expected execution output:

Step 1: files write
  Runtime Context: context_free
  Transport:       file
  Message:         wrote 5 bytes to notes.txt
Step 2: files read
  Runtime Context: context_free
  Transport:       file
  Message:         read 5 bytes from notes.txt
  Output:
  hello
capability completed: 2 step(s)

A path outside the working directory is refused before the write:

files write /etc/hosts is outside every directory policy grants write authority to (<cwd>). The path is not evaluated against a pattern — it has to resolve inside a granted root, so `..` and an absolute path elsewhere reach nothing

Exit status is 1.

4. Read the audit record

runtime audit tail -n 2

[2026-08-13T09:10:33+05:30] success consumer=human  context=context_free transport=file     command=files write                  14ms  wrote 5 bytes to notes.txt
[2026-08-13T09:10:33+05:30] success consumer=human  context=context_free transport=file     command=files read                   7ms  read 5 bytes from notes.txt

Timestamps and durations vary. The command, status, transport and context=context_free fields are the ones to match.

5. One-line health report

unset RUNTIME_CONFIG_FILE
runtime config validate

On a fresh Home with no token and no documents:

Config:   compiled default
Policy:   compiled safety profile
Safety:   compiled-safety-profile/v3 (b4671f4efe53) — invariants no document can disable
Evidence: local
Context:  owned by the tool that runs the operation (`runtime context show`)
Capabilities: ~/.engineering-runtime/capabilities
Portal:   disabled (local policy only)

GitHub will show ✗ no token found in $RUNTIME_GITHUB_TOKEN until you export one. That does not block the files path.

Authenticated GitHub follow-up

Only after the local path works. Export a scoped RUNTIME_GITHUB_TOKEN, confirm with runtime auth status, then run a GitHub capability against a repository you name. Do not mix authoring, enterprise, or Control Plane into this step.

export RUNTIME_GITHUB_TOKEN=ghp_your_token_here
runtime auth status
runtime github user get

Write your own (deeper work)

Author into your source, never silently into Runtime Home. Copy this into ./my-first.md in a disposable directory:

# My first capability

Writes a note, then reads it back.

```runtime
version: v1

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

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

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

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

An unpublished operation fails validation with this shape (exit 1):

capability is invalid:
  - workflow[0]: "does not exist" is not an operation of provider "github"

Push a validated file with runtime github file put. Full sequence: Create a Capability. Grammar: Authoring Reference.

Where to go next

If you want to…	Read
See all three run modes (local / CI / AI)	Ways to use
Understand what Bootstrap created	Runtime Home
Enable GCP, Kubernetes or OpenShift	Authentication
Change what is allowed	Policy
Where an operation runs	Where operations run
See every command	CLI Reference
Run it in a pipeline	CI/CD
Let an AI drive runtime only	AI agent

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