The Problem
Production‑grade autonomous agents need reliable state handling: crashes, long‑running pauses, and versioned deployments currently require custom scaffolding. Without a dedicated runtime, teams repeatedly re‑implement checkpointing, replay, and isolated execution, leading to brittle pipelines and costly token waste.
What This Does
kitaru supplies a self‑hosted, framework‑agnostic execution layer that sits between an agent harness (e.g., LangGraph, Pydantic‑AI) and the platform that governs it. The core Python package lives in the repository root (pyproject.toml, kitaru/init.py — not listed but implied) and provides decorators such as @flow, @checkpoint, and utilities like kitaru.wait() and kitaru.memory.
The UI and docs are a separate Next.js site in docs/ (see docs/next.config.mjs, docs/package.json). Docker support is provided via docker/Dockerfile*, enabling isolated pod execution (@checkpoint(runtime="isolated")). Example flows illustrate usage (examples/basicflow/firstworkingflow.py, examples/codingagent/agent.py).
How To Use It
Setup
Install the Python runtime pip install kitaru # from PyPI or develop locally git clone https://github.com/zenml-io/kitaru.git cd kitaru pip install -e . # editable install per pyproject.toml
Optional UI build (docs site)
cd docs pnpm install # pnpm lockfile present pnpm run build # builds the Next.js site
Configuration
Copy the template and fill in production values:
cp .env.example .env edit .env – variables such as KITARUDBURL, KITARUOBJECTSTORE, etc.
Sensitive secrets are documented in docs/content/docs/guides/secrets.mdx; ensure real values are stored securely (e.g., vault) and never committed.
Running it
A flow is a plain Python module. After installing the package, execute an example with:
python -m kitaru run examples/basicflow/firstworkingflow.py
(If the CLI entry point differs, the kitaru module’s main provides the run command.) For isolated steps, the Dockerfile can be built and pushed:
docker build -f docker/Dockerfile -t kitaru:latest .
Real‑World Use
A financial services team integrates a compliance‑review agent (examples/compliancereview/claudeagent.py). The agent is packaged as a @flow and deployed with:
from kitaru import flow, checkpoint
@flow def review(doc): result = claudeagent.analyze(doc) return result
flow.deploy(name="compliance_review", version="v1.2")
When a new regulation arrives, the team updates the prompt, redeploys a new version, and any in‑flight runs continue from the previous checkpoint without re‑processing earlier steps.
Code Health & Issues
High – Secrets exposure – docs/content/docs/guides/secrets.mdx contains placeholder credential patterns; risk if real keys are ever committed. Medium – Lack of automated tests – No tests/ directory and CI workflow (.github/workflows/ci.yml) runs linting only; untested code paths increase regression risk. Medium – Incomplete type safety – Python code lacks explicit type annotations; static analysis may miss bugs. Low – Documentation depth – Docs are extensive, but some API reference pages are missing; developers may need to read source to discover all decorator options.
No license issues (LICENSE present) and CI pipelines are configured, indicating basic SDLC hygiene.
The Bottom Line
kitaru delivers a solid, production‑ready runtime for autonomous agents, handling durability, replay, and isolated execution out of the box. It’s best suited for teams already using a Python‑based agent harness and needing a self‑hosted, version‑controlled execution environment. The main gaps are the absence of automated tests and the need for careful secret management before production rollout.