ZIZKA-AI-SL/ZizkaDB

The audit trail database for AI agents
**Tamper-evident, checksum-backed decision logs** with **session replay** and **time-travel debugging**,
built to support **EU AI Act Article 12** record-keeping.
Drift detection · MCP server · Python & TypeScript SDKs · Self-host or cloud
**Quickstart** · **Docs** · **Integrations** · **Connect** · **Cloud** · **Discussions** · **Contributing**
Every agent team eventually asks: *Why did it say that? Why did it call that tool?* ZizkaDB links every agent step to the step that caused it, so you get the answer in one call instead of scrolling through traces.
- **Causal, not just traces.** Each event carries a parent_id. db.why(event_id) walks back to the user message, wrong tool, or bad context that started it.
- **Time-travel.** db.at(agent, timestamp) rebuilds exactly what the agent knew at any past moment.
- **Tamper-evident audit trail.** Every decision is logged with a checksum, so you have a verifiable record for EU AI Act Article 12.
- **Drift detection.** See when an agent's behavior shifts from its baseline.
- **Self-host or cloud.** Run it on your own Postgres with one Docker command, or use ZizkaDB Cloud. AGPL-3.0, no per-trace billing; self-hosted data never leaves your infrastructure. Self-hosted runs **one agent with one API key**; multiple agents, agent fleets and agent-to-agent messaging are on Cloud.
Contents
- Quickstart (60 seconds)
- Integrations
- Connect your agent
- What it does
- Audit trail and EU AI Act Article 12
- How it works
- Use with your AI assistant (MCP)
- ZizkaDB vs. tracing tools
- Cloud, FAQ and docs
- Contributors
---
Quickstart (60 seconds)
One command, one container. No repo clone, no Python, no config files.
**1. Run it.** With Docker running:
This pulls a single image (Postgres, the API and the dashboard together), starts it, and logs a demo agent run. After the download, startup takes a few seconds.
**2. See why.** It prints the causal chain behind the demo agent's tool call:
**3. Explore.** The dashboard opens on that agent, already signed in: localhost:3001/dashboard/activity?agent=support-bot. Click any event → **Why? (causal)** tab.
Now log your own agent: pip install zizkadb-sdk, then see CONNECT.md. The local API is http://localhost:8000 with key zizkadb_dev_local.
Prefer plain docker run ? Day-two commands
The script is a wrapper around this:
| Do this | Command |
|---------|---------|
| Stop / start | docker stop zizkadb / docker start zizkadb |
| Logs | docker logs -f zizkadb |
| Upgrade (keeps data) | re-run the quickstart command |
| Erase everything | docker rm -f zizkadb && docker volume rm zizkadb_data |
| Dashboard port busy | ZIZKADB_DASHBOARD_PORT=3005 before the quickstart command |
The single container is for your own machine: it keeps the ports on 127.0.0.1, signs you in with one click and accepts a well-known API key. It runs without Qdrant, so semantic search and embeddings need the full stack below. For a server other people can reach, use Self-host on a server.
The self-hosted dashboard is just your dashboard: no signup, no email, no account. Accounts and plans exist only on ZizkaDB Cloud.
Self-hosted is single-agent: the first agent name you log with becomes your agent, and a second name is rejected with a message naming it. The support-bot demo agent does not count. For several agents, use ZizkaDB Cloud.
Self-host from a clone
The full stack (Postgres, Qdrant, Redis, API, dashboard as separate containers) — use this for development, semantic search, or production:
| Service | URL |
|---------|-----|
| API | http://localhost:8000 |
| Dashboard | http://localhost:3001 |
| Swagger | http://localhost:8000/swagger |