AI Agent (Runtime Agent)¶

An AI coding agent (Claude Code, Cursor, or any other) can drive Engineering Runtime only through the runtime binary. It must not call gh, kubectl, terraform, curl, or arbitrary shell for engineering work.

Engineer → natural language → Runtime Agent
                                    ↓
                              runtime binary
                 (Bootstrap → Context → Policy → Auth →
                          Execution → Audit)
                                    ↓
                           Engineering platforms

Your runtime carries its own contract

This site gets you installed, gets your first capabilities running, and explains how the pieces fit. Any Runtime command prepares the Home automatically; runtime bootstrap is the optional explicit report. Start at <Runtime Home>/RUNTIME-AGENT.md (the contract) and manifest.json (this binary's providers and operations). Specs and command cheatsheets for your installed version live in <Runtime Home>/specs/ and commands/. Read those for precise operational detail — they describe the binary you actually have. Come back here for concepts, upgrades, and anything not yet installed.

After bootstrap, paste <Runtime Home>/RUNTIME-AGENT.md into an assistant that has no hook system. The website copy, and the pointer in engineering-runtime-agent, must not override the installed Home file.

The contract repository is engineering-runtime-agent, and the contract itself is RUNTIME-AGENT.md — deliberately vendor-neutral, so one contract serves every assistant.

Just getting started?

This page is about governing an assistant. To simply use one, see Start with AI.

Set up your assistant¶

The contract repository is private today

engineering-runtime-agent is not public, so the links on this page need collaborator access. The contract itself is reproduced below so you can configure any assistant without it — copy that block.

The hook scripts (.claude/hooks/, .cursor/hooks.json, runtime-shell-policy.sh) still require repository access.

The contract — paste this into any assistant¶

Copy this into your assistant's instructions, system prompt, or rules file:

You are an interface between the user and the `runtime` binary.

Shell scope (non-negotiable). Every shell command must be runtime-mediated:
  - `runtime …`                                   all discovery and execution
  - `which runtime` / `type runtime`              locate the binary
  - `runtime … | jq|head|tail|grep|…`             parse runtime stdout only
Everything else is forbidden — gh, git, kubectl, curl, ls, cat, npm, python,
docker, cloud CLIs — even for "quick checks".

Hard rules:
1. Engineering work only through `runtime` / `runtime capability execute …`
2. Never bypass Bootstrap → Context → Policy → Auth → Execution → Audit
3. Prefer existing capabilities; otherwise author one from the Runtime Home
   `specs/` using only published provider operations
4. Discover the installed surface — `runtime <provider> --help`, Runtime Home
   `commands/` and `specs/`, plus `runtime capability list` for configured
   external sources. Do not invent operations from training data
5. Use Runtime's Auth Engine or a documented provider-native CLI session;
   never invent or persist credentials

Assistant	Setup	Enforcement
Any assistant	Paste the block above into its instructions or system prompt	None. The contract is prose the model chooses to follow — it can be ignored, and nothing stops it
Claude Code	Copy `CLAUDE.md` + `.claude/` into your project	Hooks block non-`runtime` Bash before it runs
Cursor	Copy `.cursor/rules/` + `.cursor/hooks.json`	`beforeShellExecution` denies non-`runtime` shell

"Any assistant" is the baseline and it works everywhere. The hook-capable tools are an upgrade on that baseline, not the supported path with everything else as a fallback.

Only hooks are enforcement

A prose contract is guidance. If mechanical prevention matters to you — for example because the assistant operates against production — use a tool whose hook system can deny the call, and verify it: ask the agent to run gh repo list directly and confirm it is refused.

This is a statement of fact about hook systems, not a recommendation of a vendor. Any tool that grows a pre-execution hook can enforce the same contract.

It holds no engines and no providers — execution always belongs to the installed runtime binary.

Why this exists¶

Without enforcement, agents drift into direct tool use and bypass policy and audit. The Runtime Agent layer makes the boundary mechanical:

Piece	Role
`CLAUDE.md` / Cursor rules	Reason only about runtime commands and capabilities
Skills	Discover commands, author capabilities, hand off
Claude Code hooks	Bash must be `runtime …`
Cursor hooks	`beforeShellExecution` / Shell `preToolUse` deny non-runtime

Prerequisites¶

Install runtime — Installation
Confirm the install. The first command prepares Runtime Home automatically; bootstrap makes that preparation visible:

runtime bootstrap
runtime version
runtime config validate

Authenticate platforms the agent will use (e.g. RUNTIME_GITHUB_TOKEN)
Open engineering-runtime-agent (or copy its hooks/rules into your project) so the shell policy applies
Label audit records:

export RUNTIME_CONSUMER=ai

How the agent is supposed to work¶

Understand intent from the engineer.
Discover what this installed binary can do — prefer Runtime Home contracts after bootstrap:

Path	Role
`${RUNTIME_HOME:-~/.engineering-runtime}/commands/`	Command cheatsheets
`…/specs/`	Capability grammar + per-provider authoring specs
`runtime capability list`	Reusable workflows from configured sources; any Home cache is non-authoritative

Live discovery (preferred over memorizing):

runtime config validate          # providers + allowed binaries
runtime github --help
runtime files --help
runtime resolve github repo list # does this command exist?

Resolve an existing capability, or author a Markdown capability that only uses published provider operations / allowed binaries.
Hand off:

runtime capability validate <name-or-path>
runtime capability execute <name-or-path> --input k=v …
# or a direct provider operation:
runtime github repo view cli/cli

Prefer a provider operation when one exists. Use runtime command run <binary> … only when the exact semantic mode is documented as admitted and no provider operation is suitable. Never bypass with bare helm / gh / curl.

Two surfaces (both via `runtime` only)¶

Surface	Form	Discover from
Runtime Provider	`runtime github …` / `runtime files …`	`runtime config validate` → Runtime Providers; `--help`
Command Engine	`runtime command run <binary> …`	`runtime config validate` → allowed_binaries; Home `commands/<binary>_commands.txt`

If neither surface covers the request (e.g. "create a Jira card" with no jira provider and no jira binary), the agent must refuse — not invent a bypass.

Cursor setup¶

In engineering-runtime-agent:

Path	Effect
`.cursor/hooks.json`	`beforeShellExecution` + Shell `preToolUse`
`.cursor/hooks/runtime-only-shell.sh`	Deny unless command is `runtime …`
`.cursor/rules/`	Always-on: runtime-only reasoning

After changing hooks, confirm they load in Cursor Settings → Hooks. Restart Cursor if a new hooks.json does not appear. failClosed: true means a broken hook blocks the command.

Claude Code setup¶

Path	Effect
`.claude/settings.json`	Registers Bash hooks
`.claude/hooks/runtime-only-shell.sh`	Same allow/deny policy
`scripts/runtime-shell-policy.sh`	Shared policy with Cursor

Authoring capabilities as an agent¶

Capabilities are Markdown with one ```runtime block. Grammar: Authoring reference.

Rules that matter for agents:

Exactly one of provider: or binary: per step
Never write a transport: key — the provider owns that
Start with runtime --output json capability authoring-context; use its installed contracts and exact selected source
Write only through runtime files, then validate and runtime capability plan
Treat publishing and execution as separate explicit user requests
A capability gets no special powers — each step hits the same policy/auth/audit path

Reusable company capabilities belong in the configured, version-controlled authoring worktree—typically engineering-runtime-capabilities, not only in a single machine's Home.

What the agent must not do¶

Call platform CLIs or HTTP clients directly for engineering work
Invent provider operations that runtime <provider> --help does not list
Depend on a transport ("use the REST one")
Disable or work around the shell hooks

End-to-end check¶

export RUNTIME_CONSUMER=ai
export RUNTIME_GITHUB_TOKEN=ghp_…

runtime bootstrap  # optional explicit preparation report
runtime config validate
runtime capability validate files/notes-roundtrip
runtime capability execute files/notes-roundtrip \
  --input path=./agent-note.txt --input message="from Runtime Agent"
runtime audit tail -n 5

Ask the agent something that should fail policy (e.g. force-push) and confirm it is denied and audited — not executed via raw git.

Next¶

Ways to use
Local setup — same binary, human-driven
CI/CD — same binary, pipeline-driven
CLI reference

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