---
title: Core Concepts
description: The mental model behind Kitaru's durable execution primitives
---

Kitaru sits in the **runtime layer** of your agent stack. Underneath it are the
**harness** your team picked (Pydantic AI / Pydantic AI Harness, LangGraph, Claude
Agent SDK, raw Python) and the **model(s)** that harness drives. On top sits the
**platform** your org already runs (auth, observability, policy, UI). Kitaru's
job is to make the run durable — checkpoints, replay, resume, wait states,
versioned deployments — without forcing a graph DSL or a rewrite of your
control flow.

Start with [Harness, Runtime, Platform](/concepts/harness-runtime-platform)
if you want the big-picture split, or [How It Works](/concepts/how-it-works)
for the three-planes model (control / orchestration / execution) and
what-runs-where in local dev vs production.

## Core ideas

| Concept | What it is |
|---|---|
| **Flow** | The outer durable boundary around your workflow |
| **Checkpoint** | A unit of work inside a flow whose output is persisted |
| **Execution** | A single run of a flow, identified by a unique ID |
| **Structured metadata** | Key-value data you attach to executions and checkpoints with `kitaru.log()` |
| **Runtime log storage** | Where runtime logs are sent (configured separately from structured metadata) |
| **Active stack** | The default execution target used when no per-run `stack=...` override is passed |

## What you can use today

Kitaru's current release includes:

- `@flow` — mark a function as a durable workflow
- `@checkpoint` — mark a function as a persisted work unit
- `kitaru.log()` — attach structured metadata to the current scope
- `kitaru.wait()` — pause a flow until external input is supplied
- `kitaru.llm()` — make tracked model calls with prompt/response capture
- `kitaru.connect()` — connect to a Kitaru server
- `kitaru.configure()` — set process-local runtime defaults
- `kitaru.save()` / `kitaru.load()` — persist and load named artifacts in checkpoints
- `kitaru.list_stacks()` / `kitaru.current_stack()` / `kitaru.use_stack()` — manage the default stack
- `KitaruClient` — inspect executions, fetch logs, resolve waits, retry, replay, and browse artifacts
- `FlowHandle` — interact with a running or finished execution

<Callout type="info">
  All of the primitives listed here ship today. Some capabilities are
  backend-dependent — for example, runtime log retrieval requires a
  server-backed connection — but they are part of the supported Kitaru surface.
</Callout>

## Explore the concepts

<Cards>
  <Card
    title="Harness, Runtime, Platform"
    description="Where Kitaru fits in an agent stack, and where it doesn't"
    href="/concepts/harness-runtime-platform/"
  />
  <Card
    title="How It Works"
    description="Server, runner, execution targets; three planes; local dev vs production"
    href="/concepts/how-it-works/"
  />
  <Card
    title="Flows"
    description="Define durable execution boundaries and control how workflows run"
    href="/concepts/flows/"
  />
  <Card
    title="Checkpoints"
    description="Break work into persisted units with concurrency support"
    href="/concepts/checkpoints/"
  />
  <Card
    title="Logging and Metadata"
    description="Attach structured data to executions and checkpoints"
    href="/concepts/logging/"
  />
</Cards>
