> ## Documentation Index
> Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Checkfu from source

> Run an owned Checkfu API, Runner, mock harness, and dashboard from a source checkout.

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.

<Warning>
  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](/getting-started/quickstart).
</Warning>

## 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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm bootstrap
pnpm run doctor
```

`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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm exec checkfu dev --detach --mock-only
```

`--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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
CHECKFU_CONNECTION_FILE="<printed connection path>" pnpm exec checkfu session chat "hello"
```

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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm exec checkfu dev status
```

Stop the stack and remove its owned runtime state and credentials:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm exec checkfu dev down
```

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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm exec checkfu dev --mock-only
```

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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm exec checkfu dev --harness codex
```

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](https://github.com/andyrewlee/checkfu/blob/main/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.