RiskKernel

The risk engine for your AI agents.

Deterministic cost / loop / time budgets · full observability · crash-resumable runs · human-approval gates · a memory you own.
Self-hosted. Your keys. No telemetry. Point it at your existing agents — one env var.

_{A runaway agent, stopped. It loops over a codebase; the deterministic governor halts it at its loop budget with an HTTP 402 — no model call escapes the cap. (runnable example)}

The problem

Production AI agents fail in the same handful of ways, every time: runaway loops, surprise token bills, no failure recovery, no observability, no human-in-the-loop, no governance. Agent frameworks (LangGraph, CrewAI, AutoGen) orchestrate the reasoning — but none of them ship the guardrails that keep a run from burning $400 in a midnight loop while you sleep.

RiskKernel is the deterministic, run-level reliability layer that sits in front of your agents and enforces hard limits. The LLM proposes; deterministic Go code disposes. Every irreversible action is gated.

It is not another gateway (LiteLLM/Portkey own routing), not another observability dashboard (Langfuse/Phoenix own traces), and not a content-guardrails engine (Guardrails AI/NeMo own PII/jailbreak). It interoperates with all of those and competes on the one thing nobody ships in a single self-hosted binary: deterministic run controls — the agent SRE layer.

What it does

Three ways to adopt — pick the one that fits

1. Proxy (zero code). Set one env var: OPENAI_BASE_URL=http://localhost:7070/v1. Every call is intercepted, budgeted, logged, checkpointed, and forwarded to the real provider with your key.
2. Python SDK (deep control). Install the SDK (from source today — see the Quickstart), then @governed_run / @governed_tool / runtime.budget(...) / ApprovalGate. Adapters for the Claude Agent SDK, OpenAI Agents SDK, and LangChain.
3. OpenTelemetry (universal). RiskKernel is an OTLP endpoint and emitter — govern apps already instrumented with OpenLLMetry / the OpenAI Agents SDK, and export to the backend you already run.

Quickstart (60 seconds)

Run the daemon with a default per-run budget and your key (nothing leaves your
machine except calls to the provider you choose):

docker run --rm -p 7070:7070 -v "$PWD/data:/data" \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e RISKKERNEL_DEFAULT_DOLLARS=0.50 \
  ghcr.io/prashar32/riskkernel:latest

Now put your existing OpenAI-compatible app under governance with one env
var — no code changes — and point it at a Claude model:

export OPENAI_BASE_URL=http://localhost:7070/v1
# your app runs unchanged; every call is metered, priced, budget-enforced

Or hit it directly and watch the governance headers:

curl -s -D- http://localhost:7070/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'X-RiskKernel-Run-Id: demo' \
  -d '{"model":"claude-sonnet-4-5","messages":[{"role":"user","content":"hi"}]}'
# → X-RiskKernel-Cost-Usd, X-RiskKernel-Tokens, X-RiskKernel-Step …
# the run is killed with HTTP 402 the moment it exceeds $0.50.

Inspect and audit, all on your disk:

riskkernel runs list                 # every governed run
riskkernel audit export <run-id>     # the cost ledger as JSON

Prefer a binary? go build -o riskkernel ./cmd/riskkernel (or make build), then
riskkernel serve. Deeper control (loops, checkpoints, approval gates) is the
Python SDK — install it from source (PyPI publish is on the roadmap):

pip install "git+https://github.com/prashar32/riskkernel.git#subdirectory=sdks/python"

See sdks/python. Trace every run in your own backend:
examples/otel.

Want to see the headline feature? examples/codebase-qa
is a runnable agent that loops over a codebase until the governor kills it on its
loop/dollar budget — the deterministic kill, end to end, with a real model.

Design principles

• Deterministic core in Go. All enforcement (budgets, kill switches, gating, routing, retries, checkpointing) lives in compiled, statically-typed code — never in an LLM.
• No telemetry, ever. Nothing phones home. It's a verifiable promise; see SECURITY.md.
• Your keys, your infra. Secrets come from env / .env / OS-keyring, never stored in state, never logged.
• Near-zero adoption friction. Every decision is judged by "how few changes must an existing user make?" One env var is the gold standard.
• Backwards compatibility is sacred. Self-hosted users can't be force-migrated. See COMPATIBILITY.md.

⭐ If this is useful

RiskKernel is a one-person, build-in-public project. If the idea resonates — or you
just want runaway agents to stop quietly burning money — a star genuinely helps:
it's how other people find it, and it tells me which parts are worth building next.

And if you actually run it, I'd love to hear where the guardrails are too strict or
too loose — open an issue. That
feedback shapes the roadmap directly.

Contributing

Contributions are welcome. Start with ARCHITECTURE.md for a
map of the codebase (and a "where do I code?" table), then
CONTRIBUTING.md for dev setup and the PR flow. We use GitHub
Flow — fork, branch off main, open a PR; CI (build & test + CodeQL) and a
maintainer review gate every merge.

Good places to start: issues tagged good first issue.
Be excellent to each other — see the Code of Conduct.

License

Apache-2.0. The runtime stays permissive, forever.