Run your first local session

Start Checkfu from a source checkout and complete one durable tool-calling turn.

This quickstart runs from a Checkfu source checkout. It needs Node and pnpm, but no hosted API key, Docker, or frontend framework.

You will start the local mock stack, scaffold a small app, and ask it to look up an order. The completed turn records the tool call, your app’s result, the agent reply, and final Session status in one event log.

This is a repository-local workflow. Checkfu does not yet have a self-service public CLI or SDK package channel. CLI access explains the current distribution boundary.

Prerequisites

• a Checkfu source checkout
• Node and pnpm
• three terminal windows

Run the checkout bootstrap once:

pnpm bootstrap

This installs the workspace and writes the ignored development configuration used by checkfu dev.

Complete the first turn

1. Start Checkfu

   Start the local API with the mock model and keep the connection-file path it prints:

   pnpm exec checkfu dev --mock-only
   
2. Create the example app

   In a second terminal, scaffold the app outside the checkout. A directory inside the repository would resolve against the monorepo instead of installing the small generated app on its own.

   pnpm exec checkfu create ../my-agent
   cd ../my-agent
   pnpm install
   export CHECKFU_CONNECTION_FILE="<path printed by checkfu dev>"
   pnpm serve
   

   pnpm serve creates and publishes the example Agent, registers its lookup_order Custom tool, creates a Session, and prints the exact chat command to run next.

3. Send a message

   Keep the app server running. In a third terminal, export the same connection file and run the printed chat command. Ask:

   Where is order 42?
   

   The Session records agent.tool_use, waits for the app’s user.custom_tool_result, then records the final agent message and returns to idle.

Re-running the app server reuses its Principal and Agent. The generated app uses only the public TypeScript SDK.

Until the SDK is published, the scaffold points @checkfu/sdk at the source checkout that created it. Moving or deleting that checkout breaks the generated app’s dependency path.

Run the timed check

The repository also has a one-command version of this journey:

pnpm golden-path

It starts the owned mock stack, provisions a fresh identity, drives one turn, and waits for the persisted session.status_idle event. The command writes a manifest under .local/scenarios/ with elapsed time, the settled Session, and the full event sequence. These artifacts contain sanitized operational data and should not be committed.

What this run covers

The local journey exercises the durable Session lifecycle and Custom-tool continuation. The mock agent response is fixed fixture content. This run does not cover hosted access, a real model, or Checkfu-managed execution.

Next steps

Run the complete local stack

Add the Runner, dashboard, Docker-backed execution, and repository diagnostics.

Understand Sessions and Runs

See why one durable Session can contain many short-lived Runs.