ctrlrun is the execution safety layer for AI agents, a Python library that sits between an agent "deciding to act" and "actually calling." It does not detect prompt injection; instead, it constrains consequences: every action is checked against rules you define before execution—allowed ones pass, sensitive ones wait for a human, forbidden ones are blocked. Actions with consequences execute at most once, strictly as approved, and leave a receipt. When the outcome is unknown, ctrlrun explicitly marks it as AMBIGUOUS rather than guessing.
Main capabilities
- Policy checks: reads the arguments about to leave the process and answers "allow to run, ask a human, or block outright." In the policy file ctrlrun.yaml, amounts use integer minor units (50000 means 500 euros), every interval is bounded at both ends, unlisted actions are denied by default, and there is no default allow.
- Approval and delegation: approval IDs are generated per run, bound to the hash of the specific action, single-use, and expire; approvals become invalid after arguments change. Delegation cannot expand permissions.
- At-most-once execution: reserved via an effect key (such as refund:txn_1) in a single atomic write; a second caller (whether process or host) is rejected.
- Unknown outcome handling: a lost reply is marked AMBIGUOUS, not FAILED; retries are refused until a human or the reconcile hook clarifies the outcome.
- Receipt chain: every attempt (including denials) produces a portable JSON receipt containing who, what, decision, approval, effect key, outcome, and policy hash, and links to the previous receipt.
- Permissions and budgets: each principal requires authorization, and an action must satisfy both the permission and policy axes, with the stricter one winning. Since 0.9, authorizations can carry budgets (metric limits within a rolling window), consumed at reservation time.
- Storage: SQLite by default (serverless, no ops), with cross-process reservation; for multi-host writes it can point to Postgres (pip install "ctrlrun[postgres]").
How to use
- Write the policy file ctrlrun.yaml declaring what the agent may do.
- Wrap consequential calls with the decorator: the decorator names the action, the effect key names the real-world consequence, and the context names the executor.
- A human approves from the shell, and the authorization is bound to the exact action hash the human read.
Integration methods include: the @protect decorator covering in-processAny call (raw model call, LangChain tool, hand-written loop, cron job); the gateway covers any language call that reaches a tool via MCP. Adapters are used to route approval decisions to the framework's own interrupts, for example ctrlrun-langgraph provides prevention and ctrlrun-openai-agents provides attribution. ctrlrun-langchain is the official LangChain middleware integration, whose CTRLRunMiddleware is placed into create_agent(middleware=[...]), gating every tool call through LangChain's own wrap_tool_call.
When It Applies
When an agent can only read and answer, ctrlrun is not needed; once it can send, pay, refund, delete, deploy, grant, revoke, approve, submit, purchase, or cancel, it is needed. Example domains include refunds, deployment, IAM, deletion, email, MCP, and nine other domains, one policy per domain.
Limitations
- It does not detect prompt injection: it constrains consequences rather than reading causes.
- It cannot provide exactly-once for uncontrolled remote commitments: it refuses to knowingly execute twice, and it does not roll back any operation.
- Receipts are chained and can detect tampering, but cannot detect truncation at the end or forged appends, because the header that would capture them is a row in the same database; ctrlrun anchor is used to solve this problem. Receipts are unsigned: tampering does not equal authorship.
- The badge indicates that the stated guarantees pass in the runtime environment; it does not represent security, compliance, certification, or audit. OWASP-AGENTIC-TOP10.md lists four items that are not covered.
Other Information
Apache-2.0 licensed, and the execution kernel will remain fully open source. Documentation is at docs.ctrlrun.dev. Installation: pip install ctrlrun && ctrlrun demo runs a demo locally.
