When your agent misbehaves, see why.
Self-hosted audit trail for AI agents — one command or one dashboard click from any step back to root cause.
This repository is the open-source self-host stack (API, tenant dashboard, SDKs, MCP). Operator admin console and VPC deploy live in private zizkadb-cloud — see docs/REPO_SPLIT.md.
Requires Docker. First image pull may take 5–10 minutes.
curl -fsSL https://raw.githubusercontent.com/Zizka-ai/ZizkaDB/main/scripts/quickstart-remote.sh | bashYou should see:
tool_call · lookup_order · ORD-8842
└── llm_response · gpt-4o
└── user_message · Why was my order delayed?
Run again anytime: pip install zizkadb-sdk && zizkadb demo
git clone https://github.com/Zizka-ai/ZizkaDB.git && cd ZizkaDB
bash scripts/setup-local.shFull guide: DEVELOPMENT.md · Troubleshooting: wiki/Troubleshooting.md
Every agent team asks: Why did it say that? Why did it call that tool?
- Log agent steps with parent_id(each step links to the one that caused it).
- Ask why — terminal: zizkadb why <event_id>or Python:(await db.why(event_id)).print()
- See the chain — walk back to the user message, wrong tool, or bad context.
Dashboard (same chain): Activity → support-bot → click an event → Why? (causal) tab.
import asyncio
from zizkadb import ZizkaDB
async def main():
async with ZizkaDB(host="http://localhost:8000") as db:
user = await db.log(agent="my-bot", event="user_message", data={"text": "Why is my order late?"})
tool = await db.log(agent="my-bot", event="tool_call", data={"tool": "lookup_order"}, parent_id=user.event_id)
(await db.why(tool.event_id)).print()
asyncio.run(main())Full guides: CONNECT.md · LangChain · CrewAI · LiveKit (voice) · MCP / Cursor
Scaffold a project: zizkadb init my-agent --template basic
pip install zizkadb-livekitOne LiveKit call → one Session in Activity (transcript only, no audio in ZizkaDB). Full guide: CONNECT.md → LiveKit · docs/integrations/livekit.md · example.
Managed cloud (Pro / Team) — optional
Same Why? feature — hosted at db.zizka.ai. No Docker to maintain.
The operator admin console, VPC deploy, and cloud-only marketing routes live in the private zizkadb-cloud repo — see docs/REPO_SPLIT.md.
† Plan targets on managed cloud; not enforced in API yet. See docs/README.md.
More features — drift, time-travel, search, GDPR
FAQ
Do I need to clone this repo?
No — the curl quickstart downloads config + Docker images only.
Do I need an API key locally?
No — http://localhost:8000 uses a built-in dev key. Dashboard: localhost:3001/login.
How is this different from Langfuse / LangSmith?
They observe span trees. ZizkaDB audits with explicit parent_id chains and db.why() on your Postgres — self-host under AGPL, no trace billing.
Voice agents with LiveKit?
Install zizkadb-livekit — one pip command, connect to Docker with ZIZKADB_HOST=http://localhost:8000. See LiveKit guide.
zizkadb demo connection refused?
Start the stack: curl -fsSL …/quickstart-remote.sh | bash or bash scripts/setup-local.sh.
Docs & community
AGPL-3.0 · MCP server MIT · Disable telemetry: export ZIZKADB_TELEMETRY=false