Quickstart

In about fifteen minutes you will run cairn locally with demo data, launch a pipeline in the sandbox, decide at a gate, and read what was recorded. Nothing here needs an API key or spends money.

1. Get cairn

You need Python 3.12 or later, uv and Node.js (the console’s dev server runs on it).

git clone <the cairn source repository> cairn
cd cairn
uv sync --extra dev
npm ci --prefix console
source .venv/bin/activate

Source access

The source repository is private during early access. Ask for access first. github.com/cairndev-sh/cairn is the project’s public page: it holds only a README, so cloning it will not give you a working checkout.

2. Start cairn with demo data

cairn dev --seed

cairn dev starts the engine on port 8000 and the console’s dev server next to it, on a local SQLite database (~/.cairn/dev.db unless you pass --db). --seed first fills a Demo workspace: a few finished pipelines, and one pipeline paused at a gate, waiting for a person.

The seed prints what it created, for example:

Seeded demo workspace demo:
  • pipelines         : 4 (14 leg runs)
  • waiting on a human: pl_3c1e7acf50690279/promote-model

Open the console at http://localhost:5173/console/ and sign in as dev, password dev. Then pick Demo in the workspace menu at the top of the page.

3. Run a pipeline in the sandbox

The dataset_readiness/import pipeline cleans a dataset (normalize, de-duplicate, check for contamination, redact personal data) and registers the result as a new dataset version. It runs locally and needs no key.

1. Open Pipelines and search for import. Select Run on its card.
2. Fill the two inputs:
   • path: the full path to cairn/packs/dataset_readiness/examples/sample.jsonl in your checkout.
   • register: a name for the dataset version, such as quickstart-sample.
3. Open Advanced · environment, saved inputs and type sandbox in Environment.
4. Select Launch.

The pipeline opens on its own page. Its one leg, clean, runs as its own run and the pipeline finishes as done within a minute.

You can start the same pipeline from the terminal:

cairn pipeline run dataset_readiness/import -e sandbox \
  -i path=$PWD/cairn/packs/dataset_readiness/examples/sample.jsonl \
  -i register=quickstart-sample

launched dataset_readiness/import  →  pl_a899133ec2c54e40
  status: running   legs: 1
  leg clean                    → running  run-flow-dataset_readiness--intake-8b7404
  leg clean                    → done  run-flow-dataset_readiness--intake-8b7404
  final: done

4. Decide at a gate

The seeded fine-tuning pipeline is paused before it promotes a model.

1. Open Approvals. Under Gates, select Approve promote-model.
2. Read the panel: the gate’s rule, the evaluation results it compared, and the pipeline’s spend against its cap.
3. Select Approve — release the gate, then confirm.

cairn records the decision against your signed-in name, re-checks the gate, and the pipeline moves on. Reject — cancel the pipeline would have stopped it instead.

5. Read the record

Open the pipeline (from the gate panel, select Open pipeline). Its page shows the status, the number of legs, the time it took and the total cost, with tabs for:

• Legs: each leg in order, with its run.
• Inputs & outputs and Config: exactly what the pipeline ran with.
• Approvals and Activity: every gate’s verdict and who decided it.

Runs lists every leg run in the workspace with its cost. Its Audit / replay tab is empty in this local setup: the hash-chained audit trail is switched on per environment, as Runs and the record explains.

Next

• Pipelines, legs and steps: what you just ran.
• Write a pipeline: your own pipeline, with a data gate and a person gate.
• Install and deploy: run cairn for a team.