CTRLRun/ctrlrun

Every action is checked against your rules before it runs. Allowed actions go through.
Sensitive ones wait for a person. Forbidden ones are blocked.
Execution safety for AI agents. A Python library that sits between the decision to act and the call that acts.
A consequential action happens at most once, exactly as approved, and leaves a receipt.
When the outcome is unknown, ctrlrun says so instead of guessing.
Runs in production on a single file, or on Postgres across hosts. Apache-2.0.
What it does
**The model guesses. ctrlrun does not.** The ticket says refund €500. The agent asks for
€5,000, one extra zero. The tool is in its list, the arguments are well formed, and the model
is completely confident. Nothing above the call disagrees, because nothing above the call is a
check: a tool being callable is not permission to call it with those arguments.
| Without ctrlrun | With ctrlrun |
|---|---|
| Nothing checks the amount. The call goes through. **€4,500 too much.** | Your rule checks the amount. The call never leaves. **€0 wrongly paid.** |
ctrlrun is that check. It reads the arguments about to leave your process and answers what may
happen to them: let it run, ask a human, or stop it cold. Four rules do the work, and each one
is a test in this repository before it is a sentence here.
| | |
|---|---|
| **Exact means exact** | Changed arguments need a new approval. |
| **Once stays once** | Same effect key, shared store, no repeat. |
| **Unknown means wait** | Confirm the outcome before retrying. |
| **Every answer is kept** | Requests, decisions and results, refusals included. |
The third one is the half people forget. A correct €500 refund commits at the provider and the
reply is lost coming back, so the agent retries. Retry libraries, agent frameworks and tool
loops collapse *this failed* into *I do not know what happened*. ctrlrun keeps them apart: a
lost reply is AMBIGUOUS, never FAILED, and a retry against an AMBIGUOUS effect is refused
until a human, or a reconcile hook, says what happened.
What ctrlrun demo shows: five failures and five refusals, byte for byte
Approval and delegation ids are generated per run; everything else is exactly what the demo
prints, and a test fails if the two drift apart. No network, no external service, under a
second. pip install ctrlrun && ctrlrun demo runs it locally in about the same time.
**Where it stops.** It does not detect prompt injection: it contains the consequence rather
than reading the cause. It cannot promise exactly-once against a remote it does not control, it
refuses to *knowingly* act twice, and it rolls nothing back. Receipts are chained, so an alteration
is detected; a truncation at the end and a forged append are not, because the head that would catch
them is a row in the same database, and closing that is what ctrlrun anchor is for. They are not
signed: alteration is not authorship. The badge above means the
**declared guarantees pass** in the setup they ran against, and it does not mean secure, safe,
compliant, certified or audited:
what the badge means
· OWASP-AGENTIC-TOP10.md
names the four entries this does not address.
If an agent only reads and answers, you do not need ctrlrun. The moment it can **send, pay,
refund, delete, deploy, grant, revoke, approve, submit, purchase or cancel**, you do.
Use it in three steps
The animation above is this section, recorded against the real library: one policy file, two
short programs, four commands, nothing staged.
**1. Install it.**
**2. Write down what the agent may do.** One file, ctrlrun.yaml. Amounts are integer minor
units, so 50000 is €500. Both ends of every band are bound, because an upper bound alone lets
a negative amount through, and a refund of a negative amount is a charge. Anything not listed is
denied; there is no default-allow.
**3. Wrap the call that has the consequence.** The decorator names the action, the effect key
names the consequence it has in the world, and the context names who is acting. stripe here
is a stand-in that records calls instead of making them.