Skip to main content
Use this path to contribute to Checkfu or evaluate the product locally. It starts an owned control plane, Runner, mock Harness, and dashboard from a Checkfu source checkout. It does not require a hosted API key.
This is a local development environment, not a packaged installation or a production deployment. Its local PGlite database, credentials, and process lifecycle do not promise parity with hosted infrastructure. For the hosted API flow, use the hosted quickstart.

​
Prerequisites

Clone the Checkfu repository and work from its root. The supported checkout requires Node 22.22.2+, 24.15.0+, or 26+, and the exact pnpm version declared by packageManager; pnpm bootstrap verifies both rather than asking you to keep a second version list in sync. The smallest setup is:
bootstrap performs the frozen install, prepares the local database, and creates ignored development configuration when it is absent. It does not overwrite an existing API configuration. doctor is read-only and reports any prerequisite that is still missing.

​
Start the mock stack

Start the stack in the background:
--mock-only uses the built-in mock Harness, never starts Docker, and does not contact hosted Checkfu services. The command waits for the API, Runner, and dashboard to be ready, then prints their dynamically selected addresses, the protected connection-file path, a sample chat command, and the log path. Copy the values printed by your run; local ports are deliberately not fixed. The connection file is created with mode 0600 and contains a local credential. Do not share or commit it. To exercise a full Session, copy the printed Try: command and run it through the source-checkout CLI. For example, replace the placeholder below with the exact path that checkfu dev printed:
The mock Harness returns deterministic content. It proves the local Session and event flow without calling a model; it is not evidence for a particular model or OCI Harness.

​
Inspect and stop it

Detached development is currently POSIX-only. Inspect the owned supervisor and its readiness:
Stop the stack and remove its owned runtime state and credentials:
The detached supervisor stores its pointer, manifests, logs, database, and connection document under .local/checkfu/dev. dev down verifies recorded process identities before signaling them and only removes resources owned by that recorded runtime. It is safe to run again after cleanup has converged. On Windows, or when you want logs in the terminal, run the stack in the foreground instead:
Press Ctrl-C for owned foreground cleanup. dev status and dev down manage detached state; they do not take ownership of an unrelated foreground process.

​
Use a real OCI Harness

The optional Docker path replaces the mock Harness with a checked-in catalog recipe:
This path requires a working Docker installation and may build an image. Keep using the printed connection path and the same status/down lifecycle. When you only need the Checkfu control plane and the event journey, stay on --mock-only: no Docker, no provider credential. checkfu-mock is the explicit local fixture default, not a production Harness default. It still creates the protected local connection credential described above.

​
Troubleshooting and maintainer proof

Run pnpm run doctor again after dependency or configuration changes. For current operational detail, failure recovery, and the release-tier concurrent-worktree proof, see the repository’s RUNNING.md. The durable maintainer proof is pnpm prove:dev-worktrees; it records its sanitized manifest under .local/proofs/dev-worktrees/. If startup fails, read the log path printed by checkfu dev. Do not delete arbitrary processes or Docker resources: use pnpm exec checkfu dev down so cleanup remains bound to Checkfu’s recorded ownership.