ZizkaDB
The audit trail database for AI agents
Tamper-evident, checksum-backed decision logs with session replay and time-travel debugging, built to support record-keeping.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
Tamper-evident, checksum-backed decision logs with session replay and time-travel debugging, built to support record-keeping.
Audit trail database for AI agents. Tamper-evident, checksum-backed decision logs with session replay and time-travel debugging to support EU AI Act Article 12 record-keeping. Drift detection, MCP, Python & TypeScript SDKs. Self-host or cloud.
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.
parent_id. db.why(event_id) walks back to the user message, wrong tool, or bad context that started it.db.at(agent, timestamp) rebuilds exactly what the agent knew at any past moment.One command, one container. No repo clone, no Python, no config files. 1. Run it. With Docker running:
curl -fsSL https://raw.githubusercontent.com/Zizka-ai/ZizkaDB/main/scripts/quickstart-remote.sh | bash
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:
tool_call · lookup_order · ORD-8842
└── llm_response · gpt-4o
└── user_message · Why was my order delayed?
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.
The script is a wrapper around this:
docker run -d --name zizkadb -p 127.0.0.1:8000:8000 -p 127.0.0.1:3001:3001 \
-v zizkadb_data:/data ghcr.io/zizka-ai-sl/zizkadb
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.
The full stack (Postgres, Qdrant, Redis, API, dashboard as separate containers) — use this for development, semantic search, or production:
git clone https://github.com/Zizka-ai/ZizkaDB.git && cd ZizkaDB
bash scripts/setup-local.sh
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
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.
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
Article 12 of the EU AI Act requires high-risk AI systems to automatically keep logs of what they did. ZizkaDB gives you that record:
GET /v1/events/verify reports any row whose fields no longer match.db.at().db.baseline() flags when an agent starts behaving differently from its history.flowchart LR
A[Your agent<br/>SDK · LangChain · CrewAI · LiveKit] -->|events + parent_id| B[ZizkaDB API]
D[Dashboard] --> B
M[MCP server<br/>Cursor · Claude] --> B
B --> P[(PostgreSQL<br/>source of truth)]
B --> Q[(Qdrant<br/>semantic search)]
B --> R[(Redis<br/>cache)]
why() walks the chain with a recursive query. No separate graph store.Ask Cursor or Claude "why did support-bot call lookup_order?" and get the chain back. Add this to your MCP config:
{
"mcpServers": {
"zizkadb": {
"command": "uvx",
"args": ["zizkadb-mcp"],
"env": { "ZIZKADB_HOST": "http://localhost:8000" }
}
}
}
For ZizkaDB Cloud, use ZIZKADB_API_KEY instead. Setup for each client: mcp/README.md. The MCP server is MIT-licensed.
Tools like Langfuse and LangSmith observe span trees. ZizkaDB audits decisions.
The same features, hosted at db.zizka.ai. No Docker to maintain.
† Plan targets on managed cloud; not enforced in API yet. See docs/README.md.
Do I need to clone this repo?
No. The curl quickstart downloads config and Docker images only.
Do I need an API key locally?
No. http://localhost:8000 uses a built-in dev key.
zizkadb demo says connection refused?
The stack isn't running. Start it with the curl command above or bash scripts/setup-local.sh.
Thanks to everyone who has helped build ZizkaDB. Want to join? Read CONTRIBUTING.md or pick up an open issue.
Audit trail database for AI agents. Tamper-evident, checksum-backed decision logs with session replay and time-travel debugging to support EU AI Act Article 12 record-keeping. Drift detection, MCP, Py
總覽
Audit trail database for AI agents. Tamper-evident, checksum-backed decision logs with session replay and time-travel debugging to support EU AI Act Article 12 record-keeping. Drift detection, MCP, Python & TypeScript SDKs. Self-host or cloud.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
ZizkaDB 透過 stdio 在本機執行。
上次檢查時間:2026-11-17。 Audit trail database for AI agents. Tamper-evident, checksum-backed decision logs with session replay and time-travel debugging to support EU AI Act Article 12 record-keeping. Drift detection, MCP, Python & TypeScript SDKs. Self-host or cloud.