Configure Providers¶

Goal: understand which providers this binary exposes and how to govern their operations.

A Runtime Provider owns one platform's operation surface and decides, per operation, how to reach it.

Runtime (auth, config, policy, dispatch)
   │
   ▼
GitHub Provider   repo list / pr list / workflow run / issue create
   │
   │ decides internally, per operation
   ▼
gh CLI  OR  REST API  OR  GraphQL

The runtime core owns exactly four things — authentication, configuration, policy and dispatch. It holds no per-operation knowledge of any platform.

Registered providers¶

Provider	Auth provider	Operations	Page
`github`	`github`	20 across REST, GraphQL and the `gh` CLI	github
`files`	none	5 direct file operations plus 21 typed structured edits, all File Engine	files

Counts above verified against runtime config validate on the release this site documents (github 20 = 10 rest + 2 graphql + 8 cli; files 5 file). Your binary is authoritative if they disagree:

runtime config validate     # lists each provider, its auth provider, and its
                            # operation count broken down by transport

You never choose the transport¶

A provider picks a transport per operation — rest, graphql, cli or file. The runtime never branches on it; it only maps the transport to an engine and records it in the audit log.

runtime github repo list       # REST
runtime github repo summary    # GraphQL — one round trip replaces four REST calls
runtime github pr list         # the gh CLI — the better surface for that job

You wrote the same shape of command each time. Moving an operation from REST to GraphQL changes no runtime code, no policy, and no capability.

runtime github --help          # every operation, plus the transport chosen for it

The transport column is shown for transparency. It is information, not a choice — nothing you write should depend on it. A capability that depends on "the REST one" breaks when the provider changes its mind.

Runtime Engines¶

Execution is performed by four engines. You never select one directly; the transport determines it.

Engine	Responsibility
REST	Generic REST pass-through — method, path, fields, headers and endpoint all supplied by a provider
GraphQL	Generic GraphQL pass-through — query, variables and endpoint supplied by a provider
Command	Runs one pinned binary from `allowed_binaries`, with per-binary subcommand policy, in an environment Runtime builds
File	read / write / append / delete / list, inside a granted root only

Authentication is a service, not a fifth engine. Runtime validates your platform-native credential (GitHub token, gcloud/ADC, kubeconfig, oc session) before the engine runs. It executes no operation and nothing dispatches to it, which is why the transport= in your audit log is always one of the four above.

The REST and GraphQL Engines are genuinely generic: they carry no default host and refuse an unrooted path or any URL that would change host. A missing base URL is an error, not a silent redirect. The endpoint arrives on the provider's own invocation, so one provider can never send its requests — or its bearer token — to another provider's host.

Extensibility, stated honestly. Providers are compiled into the binary. Adding a platform is a new package under providers/ plus one import line, and it needs a new release — there is no plugin ABI, and Runtime will not load a third-party provider at runtime. runtime <provider> --help lists what your installed release actually has.

Governance¶

Provider operations are governed by the providers: block in policy-config.yaml:

providers:
  github:
    enabled: true
    denied:
      - api DELETE

A provider with no entry is fully allowed. Operations are discovered from the provider, so nothing has to be listed before it can run.
Rules are evaluated on the operation, never the transport — a denial cannot be sidestepped by a provider changing how it reaches the platform.
When a provider picks the cli transport, allowed_binaries and command_policy still apply on top.

Authentication¶

Each provider declares its Auth Engine provider once, for every operation it exposes, whatever transport it picks. A CLI-backed GitHub operation authenticates as github exactly like a REST-backed one.

files declares none — its operations never touch a network or a credential, so the Auth Engine is skipped entirely.

Two senses of provider

A Runtime Provider is an operation surface (github, files). An Auth Engine provider is a credential source (github, gcp, kubernetes, openshift). A Runtime Provider names the Auth Engine provider it uses.

When no provider covers a platform¶

Use the Command Engine escape hatch:

runtime command run terraform plan
runtime command run kubectl get pods

It is governed by allowed_binaries and command_policy, and every invocation is audited — but it pins you to one tool's exact CLI, with no curated surface above it.

What if your platform isn't listed?¶

Providers ship compiled into the binary, so a new operation only arrives by installing a new runtime version. That is deliberate: the same binary always exposes the same surface, which is what makes execution reproducible.

You have three options today, in order of preference:

Check whether an existing operation already covers it. The github provider's api and graphql operations reach any endpoint on that platform, curated or not.
Use the Command Engine. Twenty-one CLI tools are permitted out of the box — Terraform, kubectl, Helm, the cloud CLIs and more. Governed and audited like everything else.
Compose a capability. Operations sequenced into a reusable workflow, with no new runtime release required.

If none of those fit, a new provider is a genuine gap worth raising — open an Issue describing the platform and the operations you need.

When a new provider does ship, it arrives here with a full page of its own — operations, transports, auth, governance and capability usage — the same shape as github and files.

Next¶

Run Capabilities

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