Run Capabilities¶

Goal: validate a capability against the installed binary, preflight its effective policy without side effects, then execute it only when authorized.

The working loop for capabilities. Command-level detail is in runtime capability; this page is the practice.

Building your first one? Create a Capability walks the full sequence; this page goes deeper on the validate/execute half of it.

Always validate first¶

runtime capability validate ./my-cap.md
runtime capability plan     ./my-cap.md --input path=./notes.txt
runtime capability execute  ./my-cap.md --input path=./notes.txt

Validation resolves every step against the operation surface of the binary you are running, so a typo, a renamed operation or a binary missing from allowed_binaries fails before anything executes.

It reports every problem it finds, not just the first — so one run tells you everything to fix.

What validation checks¶

Check	Failure looks like
`version` present	missing `version`
At least one step	no workflow steps
Exactly one of `provider` / `binary` per step	a step setting both, or neither
Provider is registered	a step naming an unregistered provider
`args` resolve to a real operation	a step whose args don't match any operation of that provider
`binary` is in `allowed_binaries`	a step naming a binary policy doesn't permit
Only known keys	an unrecognized key, named with its line number

${...} placeholders are probe-substituted before operation matching, so unresolved inputs don't produce confusing false failures.

What validation does not promise¶

A capability that validates is well-formed and only references things this runtime version can run. It can still fail at execution:

missing or expired credentials
a step denied by policy
a network error
an operation that is valid but wrong for the target (a repo that doesn't exist)

Validation is a structural guarantee, not a success guarantee.

Plan before execution¶

runtime capability plan /path/to/capabilities/files/notes-roundtrip.md \
  --input path=./notes.txt --input message=hello

Plan applies required-input substitution, context and the same compiled and declarative policy decisions execution will use. It reports all denied steps and exits non-zero on denial or missing inputs. It performs no authentication, network/process execution, mutation or audit write. Identity allow-list checks remain deferred until execution resolves an identity.

A successful plan is review evidence, not permission to execute.

Executing¶

runtime capability execute /path/to/capabilities/files/notes-roundtrip.md \
  --input path=./notes.txt \
  --input message=hello

Execution re-validates, checks required inputs, substitutes ${name}, then runs each step in order.

Machine-readable output¶

runtime --output json capability execute /path/to/capabilities/files/notes-roundtrip.md \
  --input path=./notes.txt --input message=hello

Returns a result covering every step. --output is a global flag, so it goes before capability.

Execution semantics¶

Stops at the first failing step. Steps before it have already run and are already audited.

step 1  ✓ executed, audited
step 2  ✓ executed, audited
step 3  ✗ failed  → execution ends here
step 4    never runs

Capabilities are not transactional

There is no rollback. If a workflow creates a repository in step 2 and fails in step 7, the repository still exists.

Design for this: put the destructive or expensive steps late, make workflows re-runnable where you can, and where you can't, say so in the prose. Several published examples are deliberately not idempotent — they create a fresh target per run instead.

Each step's own audit record is written, including the transport its provider chose. The capability itself contributes no execution logic and no separate record.

The authoring loop¶

Installed Runtime is the authority. Read <Runtime Home>/RUNTIME-AGENT.md and manifest.json, not a website catalog.

# 1. discover locally
runtime version
runtime --output json capability authoring-context
runtime github --help
runtime capability list

# 2–5. write through Runtime into the reported source, then compile/preflight
runtime capability validate ./my-cap.md
runtime capability plan ./my-cap.md --input key=value

# 6. only when separately requested, push through Runtime
runtime github file put owner/repo capabilities/my-cap.md \
  message="Add my-cap" content="$(cat ./my-cap.md)"

# 6. confirm what actually happened
runtime audit tail -n 10 --output json

Do not use github api PUT …/contents/…, git, gh or curl to finish this loop. Omit sha to create-only; pass sha=<blob> to compare-and-set an existing path. A successful validate is not permission to execute.

Validating a whole directory¶

Worth doing after every runtime upgrade — an operation may have changed:

CAPABILITY_SOURCE=~/work/team-capabilities

find "$CAPABILITY_SOURCE" -name '*.md' -print0 |
  while IFS= read -r -d '' f; do
    runtime capability validate "$f" >/dev/null || echo "FAILED: $f"
  done

In CI, drop the >/dev/null and let a non-zero exit fail the job. See CI/CD.

Diagnosing a failure¶

Symptom	First check
`unregistered provider`	`runtime config validate` — is the provider in the Runtime Providers section?
Args don't resolve to an operation	`runtime <provider> --help` — the operation may not exist in your version
`binary not allowed`	`runtime config validate` — your `policy-config.yaml` may predate the release that added it
Step denied by plan but validated fine	Policy denies the substituted arguments, not the operation. Check Policy
Missing required input	Supply the requested `--input key=value`; do not invent it
Works by path, fails by name	Check `runtime capability list` for the configured source, winner and digest

More: Troubleshooting.

Next¶

Create a Capability

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