Quick Start¶

From an installed binary to a governed, audited operation — and your first capability. Roughly ten minutes.

Already need to install? See Installation.

1. Bootstrap¶

runtime bootstrap

This creates your Runtime Home and fills it from assets embedded in the binary. It runs automatically before every other command, so you never have to remember it — run it explicitly here just to see what happened.

runtime bootstrap --output json    # structured: seeded / refreshed / pruned files

See Runtime Home for the full layout and ownership rules.

2. Authenticate¶

The runtime never issues or stores credentials. It validates what the platform already gave you.

Authenticate using the platform. Govern using the runtime.

For GitHub, export a personal access token:

macOS / LinuxWindows (PowerShell)

# add to ~/.zshrc or ~/.bashrc so it persists
export RUNTIME_GITHUB_TOKEN=ghp_your_token_here

setx RUNTIME_GITHUB_TOKEN "ghp_your_token_here"

Then confirm:

runtime auth status

Other providers are CLI-native — log in with the tool itself, then enable the provider in config.yaml. See Authentication.

3. Verify the whole setup¶

runtime config validate

One read-only report that answers "why isn't this working" before anything executes: where your config, policy, context and capabilities live; which auth providers are enabled and whether they actually authenticate; which allowed binaries are installed; and any policy rule that can never match.

Config:   /Users/you/.engineering-runtime/config.yaml
Policy:   /Users/you/.engineering-runtime/policy-config.yaml
Context:  /Users/you/.engineering-runtime/context.yaml (active: default)
Capabilities: /Users/you/.engineering-runtime/capabilities

Auth Providers:
  PROVIDER    ENABLED  BINARY  INSTALLED  AUTH STATUS
  github      yes      -       -          ✓ subject=your-login
  ...

4. Run your first operations¶

Provider operations — a curated surface. You name what you want; the provider decides whether it goes out over REST, GraphQL or a CLI:

runtime files write ./notes.txt hello world
runtime files read ./notes.txt

runtime github user get
runtime github repo list
runtime github repo view cli/cli

Nothing needs allow-listing first — policy governs by denial.

Any allowed binary — the escape hatch for tools no provider covers:

runtime command run git status
runtime command run gh repo list --limit 5
runtime command run terraform plan
runtime command run kubectl get pods

gh needs no gh auth login — the runtime forwards your validated token as GH_TOKEN.

Discover what is available¶

Every command has a copy-paste cheatsheet inside your Runtime Home, refreshed with every new binary version:

ls ~/.engineering-runtime/commands/
cat ~/.engineering-runtime/commands/github_commands.txt

And the live operation surface is always one flag away:

runtime github --help      # every operation, plus the transport the provider chose
runtime files --help

Start there rather than guessing — the cheatsheets are validated against the binary you have installed.

5. Watch governance work¶

Every operation leaves a record — success, failure and denial:

runtime audit tail -n 10
runtime audit tail --output json

Try a denied one:

runtime command run git push --force

It is refused by policy before git is ever invoked, and the denial is audited exactly like a success would be.

6. Run a shipped capability¶

Your Runtime Home ships with working examples. The files ones are auth-free and are the right first thing to run:

ls ~/.engineering-runtime/capabilities/files/

runtime capability validate files/notes-roundtrip
runtime capability execute files/notes-roundtrip \
  --input path=./hello.txt --input message="my first capability"

Always validate before execute — validation resolves every step against what this binary can actually do, so a typo fails before anything runs.

7. Write your own¶

Create ~/.engineering-runtime/capabilities/my-first.md:

# 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}"]
```

The prose is for humans; only the fenced ```runtime block executes.

runtime capability validate my-first
runtime capability execute my-first --input path=./mine.txt --input message=hello

# machine-readable result covering every step
runtime --output json capability execute my-first \
  --input path=./mine.txt --input message=hello

Rules worth knowing up front:

Exactly one of provider: or binary: per step.
Never write a transport. transport: is not a key — the provider owns that decision.
Every required: true input must be supplied, or nothing runs.
A capability gets no special powers: each step passes through the same context, policy, auth and audit as any other command.

Ready for a real one? Create a Capability walks the full sequence — finding the operations, proving them, writing, validating, and sharing it with your team. Full grammar: Capability 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
Point operations at a different org	Runtime Context
See every command	CLI Reference
Run it in a pipeline	CI/CD
Let an AI drive `runtime` only	AI agent