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¶
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.
See Runtime Home for the layout.
2. Confirm the empty inventory¶
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:
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:
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¶
[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¶
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:
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.
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):
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.