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.

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)

From zero to your first causal chain with one command. No repo clone needed.

1. Start Docker. Docker must be running, Starts take seconds.

2. Install and run. This downloads config and pre-built images, starts Postgres, Qdrant, Redis, the API and the dashboard, then runs a demo agent:

curl -fsSL https://raw.githubusercontent.com/Zizka-ai/ZizkaDB/main/scripts/quickstart-remote.sh | bash

3. See why. The demo prints the causal chain behind the agent's tool call:

tool_call · lookup_order · ORD-8842
  └── llm_response · gpt-4o
        └── user_message · Why was my order delayed?

4. Open the dashboard. localhost:3001 → Open my dashboard → Activity → click any event → Why? (causal) tab.

The self-hosted dashboard is just your dashboard: no signup, no email, no account. Accounts and plans exist only on ZizkaDB Cloud.

Run the demo again anytime: pip install zizkadb-sdk && zizkadb demo

Self-host from a clone

git clone https://github.com/Zizka-ai/ZizkaDB.git && cd ZizkaDB
bash scripts/setup-local.sh

Self-host on a server

On a machine other people can reach, set these in infra/.env before starting the stack:

ENV=production                      # turns off the one-click button and dev API keys
DEV_API_KEY=<random>                # must not be the default, or the API refuses to start
JWT_SECRET=<random>                 # openssl rand -hex 32 (also JWT_REFRESH_SECRET)
DEPLOYMENT_MODE=self_hosted
SELFHOST_ADMIN_TOKEN=<long-random>  # python -c "import secrets; print(secrets.token_urlsafe(32))"

The dashboard then asks for the admin token instead of showing the one-click button. Without SELFHOST_ADMIN_TOKEN, dashboard login stays disabled. Everyone who has the token signs in to the same single owner workspace. Check your config with bash scripts/validate-selfhost-config.sh --production. Full steps: wiki/Self-Hosting.

Full guide: DEVELOPMENT.md · Troubleshooting: wiki/Troubleshooting.md

Integrations

Works with the stack you already use — add one package and every step is logged with its cause.

Click a name for its setup guide. New project? Scaffold one with zizkadb init my-agent --template basic.

Connect your agent

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())

import { ZizkaDB } from 'zizkadb-sdk'

const db = new ZizkaDB({ host: 'http://localhost:8000' })

const user = await db.log({ agent: 'my-bot', event: 'user_message', data: { text: 'Why is my order late?' } })
const tool = await db.log({ agent: 'my-bot', event: 'tool_call', data: { tool: 'lookup_order' }, parentId: user.eventId })
;(await db.why(tool.eventId)).print()

From the terminal: zizkadb why <event_id>. Full guide: CONNECT.md

What it does

| Function | What you get | | --- |