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.

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 as ghcr.io/evs-cmd/cairn-engine. 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