Self-Host

Run the full ZizkaDB stack on your server. Free forever (AGPL), no cloud account required. SDK, MCP, and dashboard all connect to the same local tenant.

One rule: SDK/MCP and dashboard must use the same tenant.

Local dev (just you): login → Open my dashboard → + SDK with host=
Production / team on your server: email OTP login → create API key in Settings → use that key in SDK/MCP

Mixing email login with the auto dev key shows an empty dashboard.

Stack: Postgres + pgvector, Qdrant, Redis, FastAPI. Starts in under 60 seconds with Docker Compose.

Quickstart (recommended)

bashgit clone https://github.com/ZIZKA-AI-SL/ZizkaDB
cd ZizkaDB
bash scripts/quickstart.sh

One command: Docker stack + db.why() demo + dashboard link. Pre-built images from ghcr.io/zizka-ai/ when available.

Stack only: bash scripts/setup-local.sh · Connect guide: CONNECT.md

Run the lineage demo again

bashpip install "zizkadb-sdk>=0.5.0"
zizkadb demo

Worked example: worked/01-support-order-delay

Manual setup (optional)

bashgit clone https://github.com/ZIZKA-AI-SL/ZizkaDB
cd ZizkaDB
cp .env.example infra/.env

Edit infra/.env:

bashOPENAI_API_KEY=sk-...          # optional: hybrid search (keyword search works without it)
JWT_SECRET=your-random-32-char-secret
DEV_API_KEY=zizkadb_dev_local       # default local dev key (SDK auto-sends this)

# Optional: email OTP for production dashboard login
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=465
EMAIL_USER=you@gmail.com
EMAIL_PASS=your-app-password

Start the API stack

bashdocker compose -f infra/docker-compose.yml up -d --build

bashcurl http://localhost:8000/health
# {"status":"ok","version":"0.1.0"}

Connect SDK or MCP

Self-hosted SDK calls auto-send the local dev key (zizkadb_dev_local by default). Create a named API key in the dashboard Settings when you move to production.

pythonfrom zizkadb import ZizkaDB
db = ZizkaDB(host="http://localhost:8000")

MCP: ZIZKADB_HOST=http://localhost:8000 (dev key auto-injected on localhost)

REST: Authorization: Bearer zizkadb_dev_local

Open the dashboard

With bash scripts/setup-local.sh, dashboard is at http://localhost:3001/login. Click Open my dashboard → — no email required.

Or run manually: docker compose -f infra/docker-compose.yml -f infra/docker-compose.dashboard.yml up -d

Production on your VPS

For production on a VPS:

bashdocker compose -f infra/docker-compose.yml up -d
bash infra/deploy-selfhost.sh
# Set EMAIL_* in infra/.env for team login; set NEXT_PUBLIC_DEV_MODE=false

Point nginx to :3001 (dashboard) and :8000 (API) — see infra/nginx.conf.

Troubleshooting

API not starting

docker compose -f infra/docker-compose.yml logs api --tail=50

Dashboard empty but SDK logs work

Use "Open my dashboard →" (dev login) with host= SDK — or create an API key in Settings and use it in your agent.

Search not working

Set OPENAI_API_KEY in infra/.env and restart api container.

Port 8000 in use

Change port mapping in infra/docker-compose.yml.