Skip to content

AI Agent (Runtime Agent)

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

Engineer → natural language → Runtime Agent
                                    ↓
                              engrt 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; engrt 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 `engrt` binary.

Shell scope (non-negotiable). Every shell command must be runtime-mediated:
  - `engrt …`                                   all discovery and execution
  - `which engrt` / `type engrt`              locate the binary
  - `engrt … | jq|head|tail|grep|…`               parse ENGRT 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 `engrt` / `engrt 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 — `engrt <provider> --help`, Runtime Home
   `commands/` and `specs/`, plus `engrt 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-engrt Bash before it runs
Cursor Copy .cursor/rules/ + .cursor/hooks.json beforeShellExecution denies non-engrt 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 engrt 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 engrt commands and capabilities
Skills Discover commands, author capabilities, hand off
Claude Code hooks Bash must be engrt …
Cursor hooks beforeShellExecution / Shell preToolUse deny non-engrt shell

Prerequisites

  1. Install engrt — Installation
  2. Confirm the install. The first command prepares Runtime Home automatically; bootstrap makes that preparation visible:
engrt bootstrap
engrt version
engrt config validate
  1. Authenticate platforms the agent will use (e.g. ENGRT_GITHUB_TOKEN)
  2. Open engineering-runtime-agent (or copy its hooks/rules into your project) so the shell policy applies
  3. Label audit records:
export ENGRT_CONSUMER=ai

How the agent is supposed to work

  1. Understand intent from the engineer.
  2. Discover what this installed binary can do — prefer Runtime Home contracts after bootstrap:
Path Role
${ENGRT_HOME:-~/.engrt}/commands/ Command cheatsheets
…/specs/ Capability grammar + per-provider authoring specs
engrt capability list Reusable workflows from configured sources; any Home cache is non-authoritative

Live discovery (preferred over memorizing):

engrt config validate          # providers + allowed binaries
engrt github --help
engrt files --help
engrt resolve github repo list # does this command exist?
  1. Resolve an existing capability, or author a Markdown capability that only uses published provider operations / allowed binaries.
  2. Hand off:
engrt capability validate <name-or-path>
engrt capability execute <name-or-path> --input k=v …
# or a direct provider operation:
engrt github repo view cli/cli

Prefer a provider operation when one exists. Use engrt 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.

Experimental MCP proof (v0.11.0)

Experimental

This is a bounded proof shipped in v0.11.0. It is not a stable Engineering Runtime MCP contract.

engrt mcp serve --stdio serves newline-delimited JSON-RPC on stdin/stdout to any MCP-capable client. It exposes exactly one read-only tool, github_repo_view. Each call runs the same governed operation as engrt github repo view <owner>/<repo>, with the same:

  • authentication;
  • context;
  • policy;
  • canonical result;
  • evidence.

Evidence adds interface: mcp with the compiled tool identity: interface_tool: github_repo_view and interface_schema_digest, the SHA-256 of the tool's argument schema. Provider transport stays truthful. For the same repository state, a CLI call and an MCP call return the same canonical result: for a present repository, a policy denial and a 404. The exception is per-call metadata that is real and differs between any two separate calls: measured timing such as duration_ms, and the provider's request ID (result.http.request_id). The MCP server has no separate credentials, policy or result schema.

Two surfaces (both via engrt only)

Surface Form Discover from
Runtime Provider engrt github … / engrt files … engrt config validate → Runtime Providers; --help
Command Engine engrt command run <binary> … engrt 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 engrt …
.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 engrt --output json capability authoring-context; use its installed contracts and exact selected source
  • Write only through engrt files, then validate and engrt 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 engrt <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 ENGRT_CONSUMER=ai
export ENGRT_GITHUB_TOKEN=ghp_…

engrt bootstrap  # optional explicit preparation report
engrt config validate
engrt capability validate files/notes-roundtrip
engrt capability execute files/notes-roundtrip \
  --input path=./agent-note.txt --input message="from Runtime Agent"
engrt 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

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