Skip to content

Tutorials

Short, ordered walks. Each builds on Quick Start.

1. First governed file operation

No token required.

engrt bootstrap  # optional: show automatic Home preparation
engrt files write ./tutorial.txt "hello from runtime"
engrt files read ./tutorial.txt
engrt audit tail -n 5

You used a provider operation. Policy, context and audit still ran.

2. First GitHub operation

export ENGRT_GITHUB_TOKEN=ghp_…
engrt auth status
engrt github user get
engrt github repo view cli/cli

See GitHub authentication.

3. Watch policy deny something

engrt command run git push --force
engrt audit tail -n 3

The Command Engine refuses before git runs. The denial is audited like a success would be. Governance shape: Policy.

4. Run a published capability

engrt capability validate /path/to/capabilities/files/notes-roundtrip.md
engrt capability execute /path/to/capabilities/files/notes-roundtrip.md \
  --input path=./cap.txt --input message="tutorial"

Runtime ships no capability definitions. Use the public capability repository at a recorded revision, or another source you control.

5. Write your own capability

Create ./tutorial-echo.md in your own working tree:

# Tutorial echo

```runtime
version: v1

inputs:
  path:
    description: File to write
    required: true
  message:
    description: Contents
    required: true

workflow:
  - provider: files
    args: [write, "${path}", "${message}"]
  - provider: files
    args: [read, "${path}"]
```
engrt capability validate ./tutorial-echo.md
engrt capability execute ./tutorial-echo.md \
  --input path=./mine.txt --input message=hello

That's the mechanics. For a capability built around a real task — including how to find the right operations and prove them before you write — see Create a Capability. Full grammar: Authoring reference.

6. Configure a shared capability source

engrt capability validate github/github-repo-health

First pin the repository revision and add its directory to capabilities.sources: Sharing a Capability Source.

7. Same work in CI

Copy the minimal workflow into a repo that has ENGRT_GITHUB_TOKEN, or clone engineering-runtime-ci and run runtime-ci via workflow_dispatch.

8. Same work via an AI agent

Open engineering-runtime-agent with engrt on PATH, then ask: "Run the files notes-roundtrip capability into ./agent.txt". The agent should only invoke engrt. Details: AI agent.

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