Documentation

Complete guides for every way to integrate ZizkaDB — managed cloud or self-hosted. Pick the path that matches your stack.

Managed cloud (recommended): Sign up at db.zizka.ai/signup, create an API key in Settings, and connect via SDK, MCP, or REST. We run Postgres, Qdrant, embeddings, and the dashboard.
SDKs are stateless — pass agent, session_id, and event_id explicitly. See performance and security on the technical reference.

Choose your integration

Two paths — pick one

Path A — Managed cloud (easiest)

Best if you don't want to run servers. Everything at db.zizka.ai.

1
Sign up & create an agent

Sign up with email OTP → Dashboard → Create agent → copy the API key (zizkadb_live_…).

2
Connect SDK, MCP, or REST

Use your API key and the same agent name in every db.log(agent=…) call. Multi-agent apps: Settings → Tenant-wide API key.

3
Open your dashboard

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

Path B — Self-host (open source)

Run Docker on your laptop or VPS. Full guide in .

1
Start API + dashboard
bashdocker compose -f infra/docker-compose.yml up -d
cd dashboard && NEXT_PUBLIC_API_URL=http://localhost:8000 NEXT_PUBLIC_DEV_MODE=true npm run dev
2
Open dashboard (no email)

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

3
Log events from your agent
pythonfrom zizkadb import ZizkaDB
db = ZizkaDB(host="http://localhost:8000")  # auto-uses local dev key
await db.log(agent="my-bot", event="started", data={})
Important: Your SDK and dashboard must use the same tenant. Local dev: use the green dashboard button + host= SDK (same dev tenant). Production self-host: sign in with email OTP, create an API key in Settings, paste that key into your SDK.
4
See your data in the dashboard

Refresh /dashboard — agents appear as soon as you log events with a matching key/tenant.

After connecting (both paths)

1
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.

2
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.

3
Use drift & search

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