Tutorials¶

Short, ordered walks. Each builds on Quick Start.

1. First governed file operation¶

No token required.

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

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

2. First GitHub operation¶

export RUNTIME_GITHUB_TOKEN=ghp_…
runtime auth status
runtime github user get
runtime github repo view cli/cli

See GitHub authentication.

3. Watch policy deny something¶

runtime command run git push --force
runtime 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¶

runtime capability validate /path/to/capabilities/files/notes-roundtrip.md
runtime 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}"]
```

runtime capability validate ./tutorial-echo.md
runtime 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¶

runtime 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 RUNTIME_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 runtime on PATH, then ask: "Run the files notes-roundtrip capability into ./agent.txt". The agent should only invoke runtime. Details: AI agent.

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