Overview

cairn is a self-hosted control plane for the work behind AI. You declare an outcome; cairn drives the tools underneath and records exactly what ran. The engine is domain-neutral — everything that knows about a domain lives in a pack, and everything that touches a tool is an operator. Today it spans the ModelOps lifecycle — profile and gate a dataset, fine-tune a model, benchmark it, promote it behind a human approval, serve it — plus incident RCA, each as a single governed workflow, and chains of them as governed pipelines.

The engine — template runner, dispatcher, deterministic guards, action executor, LLM gateway, run store — knows nothing about fine-tuning. Swap the pack and the same machinery serves dataset checks, model evaluation, incident response, or infra changes.

The thesis — governed, not magic

This is what separates cairn from a bare agent loop or a black-box tool: the work runs behind deterministic guardrails you can inspect afterward.

• Hard budget — every run accrues cost in a scope; over the cap it raises BudgetExceeded, so a fine-tune can’t quietly overspend.
• Policy gating + human approval — proposed actions pass through policy rules before any executor runs; high-risk ones (promote a model, destroy a resource) pause for a human (HITL) and resume durably.
• Reproducible runs — templates are content-addressed and every run stores its validated inputs, schema hash, and the exact operators it resolved to, so a run can be replayed and explained. “It worked last week” stops being a mystery.
• Tamper-evident audit — every model call, tool call, and action lands in a hash-chained, append-only log: what ran, what it cost, who approved it.
• Citation validation — for synthesized answers, every identifier the model cites is exact-string-matched against the context it was given; unmatched citations are stripped.

One engine, many surfaces

The same governed core is driven from four places:

• CLI — the full control surface: run, preflight, replay, approve, deploy. See the CLI reference.
• Web console — a React SPA served at /console: runs, approval gates, pipelines, configuration, policies, connections, and a sandboxed Playground.
• HTTP + SSE API — everything the console does is a documented endpoint, including live run streaming. See the HTTP API.
• cairn ask — natural-language intent resolved into governed plans and runs; it never bypasses policy.

How packs and operators are discovered

Packs and operators are discovered through Python entry-point groups — not filesystem scanning. At startup the engine walks the groups, loads each Pack object, and registers it; it then reads everything it needs (templates, operators, backends, settings, doctor checks) from the registry. The engine never imports a pack module. That one-way dependency is what keeps it reusable across domains — and lets anyone publish an operator that inherits the budget, gate, and audit for free.

Next

Installation — set up a dev environment with uv, or run the engine container.

Architecture — the engine, packs, profiles, and the request lifecycle.

Packs — templates, skills, policies, and the pack contract.

Pipelines — chain governed workflows with gates, schedules, and events.

Deployment — the compose stack: one .env, profile toggles for Temporal, MLflow, and the LLM gateway.

CLI reference — the complete cairn command surface.