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¶
- Install
engrt— Installation - Confirm the install. The first command prepares Runtime Home automatically;
bootstrapmakes that preparation visible:
- Authenticate platforms the agent will use (e.g.
ENGRT_GITHUB_TOKEN) - Open
engineering-runtime-agent(or copy its hooks/rules into your project) so the shell policy applies - Label audit records:
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 |
|---|---|
${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?
- Resolve an existing capability, or author a Markdown capability that only uses published provider operations / allowed binaries.
- 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:orbinary: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 andengrt 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> --helpdoes 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¶
- 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.14.0. After bootstrap, the version-exact files in Runtime Home win.