The Problem

Teams building production agents quickly discover their harness (LangChain, Pydantic AI, etc.) handles the model loop but not durability. A crash mid-run loses progress; a long-running task can't pause for human input; deploying a new version breaks in-flight invocations. Kitaru is the runtime layer underneath: checkpoints, replay, wait(), versioned deployments, and isolated execution, self-hosted.

What This Does

Kitaru is a Python library (src/kitaru/) with a CLI (src/kitaru/cli.py) and an MCP server (src/kitaru/mcp/server.py). It wraps your agent code with @flow and @checkpoint decorators to add durable execution. The repo is a portfolio of four projects: the core src/, a site/ (94 files, Next.js marketing/docs), a docs/ (83 files, Next.js), and examples/ (71 files, 45 code files showing usage).

The README positions Kitaru as the "runtime layer" between the harness and your platform. It's framework-agnostic: you keep your SDK, prompts, and tools. Kitaru adds the execution layer, with artifact lineage to your object store and isolated step execution on Kubernetes/AWS/GCP/Azure.

How It Is Wired

Execution starts at src/kitaru/cli.py:320 (cli function) or src/kitaru/mcp/server.py:842 (main). The MCP server is the deeper entry point, reaching 391 functions; the CLI reaches only 10. The MCP server exposes operations like _deploy (reaches 201 functions) and _get_logs (167 functions).

The call graph shows KitaruClient is the hub, called from 140 places. KitaruUsageError (97 call sites) and _DummyRun (80) are next. The _stack_component_details_from_model function calls _normalize_stack_detail_value 22 times—the hottest edge.

The module graph shows a cycle in src/kitaru/adapters/pydantic_ai/: _toolset.py, _function_toolset.py, and _mcp_server.py are mutually reachable. Changing one risks breaking the others. The _toolset.py module has instability 0.73 (in cycle), meaning it's both depended-upon and dependent.

External effects: 92 functions read/write files, 10 call a model for inference, 5 run external commands, 6 do crypto/secret operations, 3 make outbound network calls. A traced path: main → _clean_output → shutil.rmtree (filesystem).

How To Use It

Setup: Install from pyproject.toml with uv pip install -e . or pip install -e .. The README shows pip install kitaru. Docker images build from docker/Dockerfile.

Configuration: Copy .env.example to .env and set backend/object store credentials. The CLI manages stacks via kitaru stack commands.

Running: The README's quick start:

pip install kitaru
export KITARU_SERVER_URL="http://localhost:8000"
kitaru server start

Then decorate a flow:

from kitaru import flow, checkpoint, wait

@flow
def my_agent(input: str):
    result = my_llm_call(input)
    checkpoint(result)
    wait()  # pause for human input
    return result

Real-World Use

A support agent that needs human approval before a refund. The flow runs, checkpoints the analysis, calls wait(), releases compute. A human reviews via the dashboard, triggers resume, and the flow continues from the checkpoint without re-running the LLM call. A crash mid-run replays from the last checkpoint, returning cached output instead of re-burning tokens.

Code Health & Issues

Static analysis found 72 findings (15 high, 57 medium) across 5 kinds:

  • High - Import cycle - src/kitaru/adapters/pydantic_ai/_toolset.py, _function_toolset.py, _mcp_server.py are mutually reachable. Break the cycle by extracting shared types.
  • High - Deep nesting - 21 files with max indentation depth 6, including _toolset.py, _model.py, client.py. Flatten with guard clauses.
  • High - Duplicated code - 512 repeated 6-line blocks across 74 files. Extract shared helpers.
  • High - Oversized files - 17 files over 1000 lines, including _stacks.py (2264 lines) and client.py. Split by responsibility.
  • Medium - Broad exception handling - 18 instances of bare except swallowing errors, in _tracking.py, _otel.py, and examples.

The code health audit adds a Critical finding: .github/workflows/site.yml exposes CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID to a workflow a fork can trigger. Move secret-using steps into a workflow_run job that never checks out PR code.

The Bottom Line

Kitaru solves a real problem—durable agent execution—and the core library is substantial. The Pydantic AI adapter cycle and oversized files will cost you during maintenance. The critical CI secret exposure must be fixed before accepting external contributions. This is for teams building agent platforms who need the runtime layer, not for those buying an off-the-shelf solution.