anwar-naveed/keel

A tiny, production-shaped agent runtime: **durable by default, gated by
design, evaluated before it ships.**
keel runs LLM agents with the boring parts done right — runs survive a
kill -9, forbidden writes are structurally impossible (not politely
declined), every decision is audited, and a behavioral eval gate runs in
CI on every push.
The problem
Most agent demos are a while True: loop around a chat API. When you need
the real thing, you discover the missing 90%: what happens when the model
half-finishes and the process dies? When a prompt injection tells it to
delete the database? When a "small refactor" silently breaks the one
guarantee your product depends on? keel is the 90% — small enough to read
in an afternoon (~1,900 LOC), shaped like a production system.
5-minute quickstart (Docker, zero keys, zero cost)
No API keys. No GPU. The MockProvider carries every test and CI run —
real-model adapters (Ollama/OpenAI/Anthropic) ship in code and are
covered by mocked-HTTP tests; point KEEL_PROVIDER at one when you have
the hardware or the key.
Architecture
| Guarantee | Mechanism | Proof |
|---|---|---|
| Runs survive SIGKILL | startup repair: running→pending, re-queued | tests/test_durability.py |
| Forbidden writes are impossible | capability objects: the method does not exist | tests/test_capabilities.py::test_injection_cannot_write |
| Staged writes need a human | review gate: running→review, keel approve/reject | tests/test_review.py |
| The audit log is tamper-evident | sha256 hash chain, keel audit verify | tests/test_audit.py |
| Behavior can't silently regress | eval gate in CI: golden + safety suites | keel eval --gate (exit 1) |
| Adding agent #31 is a file drop | YAML inventory, validated at load | tests/test_inventory.py::test_thirty_first_agent |
Supabase mapping (why this shape)
keel is deliberately built in the shape the Supabase AI Platform team
describes — the same problems, minus the Postgres:
| Supabase posting language | keel module |
|---|---|
| durable execution / retries | runtime/state.py + startup repair |
| tool calling with safety | governance/capabilities.py |
| human-in-the-loop approvals | governance/review.py |
| audit / compliance | governance/audit.py (hash-chained) |
| evals before shipping | eval/ (gate wired into CI) |
| MCP integration | mcp/server.py (FastMCP, 5 tools) |
Philosophy
- **Impossible, not forbidden.** A read-only agent's tool object has no
write attribute at all. A jailbroken model gets AttributeError.
See docs/adr-002-impossible-writes.md.
- **Behavioral evals, not string matches.** Cases assert states, tool
boundaries, audit integrity, and cost — the model's prose is not under
test. The judge is graded too (eval/selftest.py).
- **The runtime watches itself.** keel meta scans runlogs for repeated
failures, cost spikes, and tool-error drift — an agent watching the