Skip to content

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.

After installing Runtime, this walkthrough needs 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; 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.

1. Bootstrap

engrt bootstrap

Output on a fresh Home (path normalized):

Runtime Home: ~/.engrt
  created runtime home
Capabilities: ~/.engrt/capabilities
  refreshed runtime-owned specs/ and commands/ for (new runtime home) -> 0.13.0: 45 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. Any engrt command creates the Home on first use — so if you ran engrt version first, bootstrap reports runtime home already existed. Runtime writes no config.yaml, no policy-config.yaml, no context.yaml, and no example capabilities. The capabilities/ directory is created empty.

engrt version
# engrt 0.13.0

See Runtime Home for the layout.

2. Confirm the empty inventory

engrt capability list
No capabilities resolved.

That is a valid state, not a broken one — Runtime ships none and fetches
nothing. Configure capabilities.sources to directories that already hold
definitions, or set ENGRT_CAPABILITIES_DIR as both a capability source
and the authoring destination.

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. ENGRT_CAPABILITIES_DIR selects one directory as both an authoritative capability source and the authoring destination. Only the unset Home fallback is a non-authoritative compatibility cache.

JSON reports an empty capabilities array:

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

3. Run an auth-free files capability

Compiled policy grants the working directory (.) for file reads and writes. Create a self-contained fixture and work in a disposable directory:

FIXTURE_DIR="$(mktemp -d)"
cat > "${FIXTURE_DIR}/notes-roundtrip.md" <<'CAPABILITY'
# Write and read a note

```runtime
version: v1
inputs:
  path:
    description: File to write and read
    required: true
  message:
    description: Content to write
    required: true
workflow:
  - provider: files
    args: [write, "${path}", "${message}"]
  - provider: files
    args: [read, "${path}"]
```
CAPABILITY

WORK_DIR="$(mktemp -d)"
cd "${WORK_DIR}"
export ENGRT_CAPABILITIES_DIR="${FIXTURE_DIR}"
engrt capability list
engrt --output json capability list
engrt capability validate notes-roundtrip
engrt capability execute notes-roundtrip \
  --input path=./notes.txt --input message=hello

The list reports notes-roundtrip from capabilities-dir; JSON includes "authoritative": true and the digest of the exact local fixture. Expected execution output:

Capability: notes-roundtrip
Run:        01a14c43-7aef-752a-8f69-54d1094e9b58
Status:     success
Steps:      2 completed, 0 not required, 0 failed, 0 not executed

Step 1: files write
  Runtime Context: context_free
  Transport:       file
  Status:          success
  Message:         wrote 5 bytes to notes.txt

Step 2: files read
  Runtime Context: context_free
  Transport:       file
  Status:          success
  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. Try it:

engrt files write /tmp/outside.txt hello
Command:         files write
Transport:       file
Runtime Context: -
Identity:        (-, subject unresolved)
Status:          denied
Execution:       not dispatched
Message:         Policy denied this operation. Change the policy document only if this is intended.
Refusal:         policy (file_policy)
Reason:          files write /tmp/outside.txt is outside every directory policy grants write authority to
                 (<your working directory>). The path is not evaluated against a pattern — it has to resolve …
Hint:            work inside a granted directory, or add the directory to file_policy.read_roots/write_roots in your policy document

A direct command exits 1 on a denial. The same refusal inside a capability run exits 3 — see capability exit codes. Refusal: names the kind of check (policy, compiled_safety, context_unsupported, argument_invalid, auth) and its rule, and Hint: gives the recovery step; --output json carries the same as "refusal": {"class", "rule", "hint"}.

4. Read the audit record

engrt audit tail -n 3
[2026-10-18T10:47:33+11:00] success consumer=undeclared actor=someone(self_asserted) session=- context=context_free transport=file     command=files write                  capability=notes-roundtrip run=01a14c43-7ae step=1/2 engrt_version=0.13.0 9ms  operation completed
[2026-10-18T10:47:33+11:00] success consumer=undeclared actor=someone(self_asserted) session=- context=context_free transport=file     command=files read                   capability=notes-roundtrip run=01a14c43-7ae step=2/2 engrt_version=0.13.0 6ms  operation completed
[2026-10-18T10:47:33+11:00] success consumer=undeclared actor=someone(self_asserted) session=- context=-          transport=-        command=capability execute notes-roundtrip capability=notes-roundtrip run=01a14c43-7ae engrt_version=0.13.0 31ms  completed 2 of 2 steps

Timestamps, durations, run IDs and your user name vary. consumer=undeclared means nobody declared who is calling; set ENGRT_CONSUMER (human, ci or ai) to label it. Runtime never infers a human. Step records have context=context_free and transport=file; the aggregate record groups the two steps. Stored messages are coarse completion classes, not file contents or native output.

5. One-line health report

unset ENGRT_CAPABILITIES_DIR
engrt config validate

The opening lines on a fresh Home with no token and no documents:

Config:   compiled default
Policy:   compiled safety profile
Safety:   compiled-safety-profile/v4 (e6784e4c72bc) — invariants no document can disable
Evidence: local
Context:  owned by the tool that runs the operation (`engrt context show`)
Capabilities: ~/.engrt/capabilities (Home cache, non-authoritative; declare capabilities.sources for your catalog)
Portal:   disabled (local policy only)

engrt auth status reports GitHub as not ready until you choose a source — that does not block the files path:

github     ✗ auth_unavailable: github authentication: no ENGRT session; use explicit auth login github

On a host with no OS secure store (headless Linux, containers, CI) the code is auth_store_unavailable, and the message names the sources that need no store: ENGRT_GITHUB_TOKEN (source: env), a token file (source: file) or GitHub App credentials (source: github_app). A token that is set but rejected reports auth_invalid_credential.

Authenticated GitHub follow-up

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

export ENGRT_GITHUB_TOKEN=ghp_your_token_here
engrt auth status
engrt 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}"]
```
engrt capability validate ./my-first.md
engrt 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 engrt 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 engrt only AI agent

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