Installation

cairn is a Python project managed with uv. The engine ships as one wheel (cairn); each operator pack is its own wheel in the same uv workspace.

Requirements

• Python 3.12+
• uv

Set up from source

git clone https://github.com/cairndev-sh/cairn.git
cd cairn
uv sync --extra dev          # engine + workspace operators + dev deps

uv sync builds a fresh environment from the lockfile; it is enforced by CI to stay working. The dev extra brings test and lint tooling.

Verify

uv run cairn doctor          # preflight: packs, profile bindings, env, services
uv run cairn ls              # list what is installed

doctor is the fastest way to confirm the install is healthy — it checks that packs load, profile bindings resolve to registered operators, and required services are present. See the CLI reference.

To go from here to a running control plane with data in it — choosing SQLite or Postgres, seeding demo fixtures, and starting the server and console — follow the Quickstart.

Optional extras

Enable only what you need. The most commonly used:

Extra	Adds
rag	retrieval-augmented generation (embedding + parsing)
rag-sqlite-vec	zero-config local vector store (also: rag-qdrant, rag-pinecone, rag-pgvector)
pii	Presidio-backed PII detection for dataset gates
runtime-temporal	the durable Temporal runtime
runtime-dbos	lightweight durable execution (no server)
runtime-sqlite / runtime-postgres	cross-restart human-in-the-loop checkpointing
storage-postgres	Postgres run/state store
telemetry	OpenTelemetry export
auth	argon2 password hashing for server auth
tui	the cairn remote console terminal UI
oauth / infisical / nats	OAuth broker, Infisical secrets, NATS inbox
production	the production bundle: Temporal + Postgres + real dataset-check and eval operator deps in one extra

uv sync --extra dev --extra rag --extra runtime-temporal

Container image

The engine also ships as a container (Dockerfile.engine), published to a container registry. The full server stack — engine, Postgres, Caddy, and optional Temporal / MLflow / LLM-gateway / observability services — runs from one compose file with profile toggles: see Deployment.

Run the test suite

uv run pytest -q -m "not dbos"      # dbos-tier tests need: uv sync --extra runtime-dbos