Quickstart

From nothing to a running control plane with data in it. Every command here is run against a clean checkout; see Installation for the extras table and the container image, and Services to switch on Temporal, Metaflow, RAG, or the LLM gateway.

1. Install

Requires Python 3.12+ and uv.

git clone <the cairn source repository>
cd cairn
uv sync --extra dev

Source access

The source repository is currently private — ask for access before you start. github.com/cairndev-sh/cairn is a project landing page, not the source: cloning it succeeds but yields only a README, and uv sync then fails with a confusing “no pyproject.toml”.

Everything below is uv run <cmd> (or .venv/bin/<cmd> if you prefer). A cold uv sync builds the whole workspace and takes a few minutes.

2. Pick a store

cairn keeps all of its own tables in one database, chosen by a single variable, OBS_STORAGE. Nothing else needs configuring to get started.

SQLite (zero infrastructure)

export OBS_STORAGE="sqlite:///$HOME/.cairn/cairn.db"

One file, created on demand. Both spellings of an absolute path work (sqlite:///abs/path and SQLAlchemy’s sqlite:////abs/path); a path without a leading slash is relative to the working directory.

Postgres (multi-process, production)

createdb cairn
export OBS_STORAGE="postgres://cairn@127.0.0.1:5432/cairn"
uv sync --extra dev --extra storage-postgres

The storage-postgres extra brings asyncpg. Use Postgres whenever more than one process touches the data — the server and a Temporal worker, for example.

Tables are created on demand

There is no migrate step to run today. Each store issues its own CREATE TABLE IF NOT EXISTS the first time it is used, so a fresh database starts empty and grows as features are exercised. A seeded database has a handful of tables; the full schema is ~47 across the whole product.

3. Seed demo fixtures

uv run cairn demo

This creates a demo workspace with three enabled workflows, three completed runs, an audit trail, and one run paused at an approval gate — enough to make every console surface show real content. It is idempotent, so re-run it freely. Tear it down with uv run cairn demo --archive (a soft delete: runs and audit history are preserved).

4. Check the install

uv run cairn doctor      # every setting, its value, and service reachability
uv run cairn ls          # what packs and workflows are installed

doctor is the fastest way to see what cairn thinks its configuration is — it prints each knob with its resolved value or the default it fell back to.

5. Run the server

OBS_TRIGGER_PORT=8000 uv run cairn-server

cairn-server is a separate console script, not a CLI verb. It serves the API and the web console from one port:

curl -s localhost:8000/healthz
# {"ok":true,"skills_loaded":3,"environment":"production", ...}

Then open http://localhost:8000/console/ and switch to the demo workspace (top bar) to see the seeded runs.

The API is open until you set a JWT secret

With OBS_JWT_SECRET unset, every route answers unauthenticated — convenient locally, unacceptable on anything reachable. Setting it turns auth on: all routes outside a small public list (/healthz, /token, console assets, signed webhook ingress) then require a bearer token from POST /token, and users are admin-invited. See Deployment.

6. Run the console in dev mode (optional)

The server already serves a built console. You only need this if you are changing the UI and want hot reload:

npm --prefix console install
npm --prefix console run dev      # Vite dev server on :5173, proxying the API

Open http://localhost:5173/console/. To produce the bundle the server ships:

npm --prefix console run build    # type-checks, then writes console/dist

The engine image bakes console/dist in at build time, so a stale bundle is the usual cause of “my UI change didn’t show up in the container”.

Run something

--input takes the path to a JSON file of inputs, not inline key=value pairs. No sample data ships in the repo yet, so make some:

cat > /tmp/sample.jsonl <<'EOF'
{"input": "great product", "output": "thanks!"}
{"input": "call me at 415-555-0199", "output": "noted"}
EOF
echo '{"path": "/tmp/sample.jsonl"}' > /tmp/input.json

Compile and inspect the plan without executing anything — no credentials needed:

uv run cairn run dataset-readiness/check --input /tmp/input.json --dry-run
uv run cairn replay <run-id>       # the persisted trace of a past run

Executing a workflow needs a real LLM key

The flagship workflows have agentic steps, so an actual run needs a working OPENAI_API_KEY (or another configured provider). --mock does not currently isolate the run from the network — it still fails with a 401 on a dummy key. Until that’s fixed, --dry-run is the credential-free way to verify your install.

Where to next

• Services — enable Temporal, Metaflow, Prefect, RAG, LiteLLM, MLflow, and OpenTelemetry.
• Deployment — the compose stack, TLS, auth, and profiles.
• Web console — what each surface shows.