Configuring Craik Home

4 min readFor operatorsUpdated 2026-05-19

What you'll learn

• Where Craik writes state by default and how to move it.
• The directory layout craik home init creates.
• How to share a home between hosts or CI runners.
• How to inspect a home without modifying it.

The default location

Craik stores everything it persists — projects, tasks, case files, receipts, handoffs, secrets, and caches — under one product-home directory:

~/.craik/

This is intentional. One known location keeps backups, audit, and cleanup trivial. Craik does not silently create project-local .craik/ directories inside your repositories. Project-local metadata is opt-in and explicitly documented when used.

Override with CRAIK_HOME

Point Craik at any directory you control by setting CRAIK_HOME:

Move Craik home to a tmpfs sandbox

export CRAIK_HOME=/tmp/craik-sandbox
craik home init

CRAIK_HOME must:

• Be an absolute path.
• Point at a directory Craik can read and write.
• Be available before any craik command runs — Craik reads the variable at process start.

Setting CRAIK_HOME per-command works too:

One-off home override

CRAIK_HOME=/tmp/scratch craik home show

The home layout

$CRAIK_HOME/
  config/       # user-level config and credential profile definitions
  secrets/      # secret material — never committed
  state/        # SQLite store: projects, tasks, receipts, handoffs, case files
  cache/        # short-lived caches
  logs/         # diagnostic logs
  receipts/     # exported receipts
  handoffs/     # exported handoffs
  case-files/   # exported case files
  projects/     # per-project artifacts and exports

Each directory has a single, narrow purpose. Separation by data class keeps backup policies straightforward (back up state/ and secrets/; you can typically rebuild cache/) and makes audit easier (everything actor-relevant ends up in receipts/ and handoffs/).

Inspect vs initialize

craik home show

Print the resolved paths. Read-only. Does not create directories.

craik home init

Create the per-data-class subdirectories. Idempotent — safe to re-run.

Run craik home show first in any unfamiliar shell to confirm where Craik is pointing before you trigger work.

Sharing a home across hosts

A few real situations:

One workstation, many shells

Use the default ~/.craik/. Every shell sees the same home unless someone exports CRAIK_HOME.

CI runner

Set CRAIK_HOME early in the job (e.g., $GITHUB_WORKSPACE/.craik). Cache it between jobs if you want project registrations to persist; otherwise treat each job as a fresh home.

Team-shared host

Give each operator their own CRAIK_HOME under /srv/craik/<user>. Don't share state/ across operators — receipts and handoffs are bound to operator identity.

Containerized run

Mount CRAIK_HOME as a volume so receipts and handoffs survive the container. Treat secrets/ as a separate secret-tier volume.

caution

Don't put CRAIK_HOME on a network share unless you know what you're doing. The SQLite store at state/craik.sqlite is sensitive to file locking semantics. NFS will work most of the time and surprise you at the worst possible moment. Stick to local disks or volumes that promise POSIX locking.

Resetting a home

Because Craik never writes outside CRAIK_HOME, resetting state is one command:

Tear down a Craik home

rm -rf "$CRAIK_HOME"
craik home init

This wipes projects, tasks, case files, receipts, handoffs, secrets, and caches. Use it only when you really mean it.

What's next

DoRun the setup wizardAn interactive walkthrough that wires home, identity, and a first project together.DiagnoseRun doctorHealth-check Craik home, identity, credentials, and provider posture.ReferenceLocal state layoutThe on-disk shape of every directory under CRAIK_HOME.