Documentation

Open-source guides for self-hosting ZizkaDB with Docker. Start with the quickstart, then connect your stack. Managed cloud docs are at the bottom if you prefer hosted.

OSS quickstart (recommended):

bashgit clone https://github.com/Zizka-ai/ZizkaDB
cd ZizkaDB
bash scripts/quickstart.sh

Pulls pre-built GHCR images when available — no local compile. Runs the why() demo and opens the dashboard at http://localhost:3001/login (no signup). Full connect guide: CONNECT.md

Environment variables (self-host + cloud):

bashexport ZIZKADB_HOST=http://localhost:8000   # self-host only
export ZIZKADB_API_KEY=zizkadb_live_...   # managed cloud only
export ZIZKADB_AGENT=my-bot
export ZIZKADB_TELEMETRY=false            # optional

SDKs are stateless — pass agent, session_id, and event_id explicitly. See performance and security on the technical reference.

Choose your integration

OSS path — self-host with Docker

Full guide in · connect snippets in CONNECT.md

Quickstart (one command)

bashgit clone https://github.com/Zizka-ai/ZizkaDB
cd ZizkaDB
bash scripts/quickstart.sh

Starts API + dashboard. Uses pre-built ghcr.io/zizka-ai/* images when published; otherwise builds locally. Runs zizkadb demo (causal lineage).

Open dashboard (no email)

Go to http://localhost:3001/login → click Open my dashboard →. This is your local workspace.

Connect your agent

pythonpip install zizkadb-sdk
# zizkadb demo          # repeat the worked example
# zizkadb init my-agent --template basic

from zizkadb import ZizkaDB
db = ZizkaDB(host="http://localhost:8000")  # auto-uses local dev key
await db.log(agent="my-bot", event="started", data={})

Important: SDK and dashboard must use the same tenant. Local dev: green dashboard button + host= SDK. Production VPS: email OTP + API key from Settings.

See your data in the dashboard

Agents appear as soon as you log events. Click an agent for events, sessions, and drift.

Managed cloud (optional)

Prefer not to run Docker? Use hosted ZizkaDB at db.zizka.ai.

Connect SDK, MCP, or REST

Use your API key and the same agent name in every db.log(agent=…) call.

Open your dashboard

db.zizka.ai/dashboard shows the same agents and events your code logs.

After connecting

Log events with session_id

Log user_message, each tool_call, and assistant_response with parent_id links. Use the same session_id for one conversation so baselines and diffs work.

Configure embeddings (managed)

In Settings → Embeddings, pick your OpenAI model (platform-hosted or your own key). Required for semantic search and context_for(). Logging and why() work without embeddings.

Use drift & search

Once you have enough sessions, use baseline() and semantic search in the dashboard or SDK.