Quick start (Windows, Docker-based dev-builder)
If you’re on Windows, don’t try to compile the Rust workspace natively — the-gnu toolchain drags in a vendored OpenSSL build (needs a full Perl with
ExtUtils::MakeMaker/Pod::*, plus make on PATH) and hits an upstream
whisper-rs-sys bug that only shows up on MinGW/GCC. None of that is worth
fixing for a single Windows dev when CI/staging build on Linux anyway. Use the
Ubuntu container instead:
curl http://localhost:8000/api/health should return
{"database":"ok","redis":"ok","status":"healthy"}.
If any of the containers show Exited in docker ps -a (e.g. after a Docker
Desktop restart), docker start them again — data persists in the container’s
volumes.
Signing in without real email delivery
Local dev doesn’t send real magic-link emails. Request a sign-in from the UI as normal (enter the email, submit), then pull the token straight from Postgres instead of an inbox:http://localhost:5173/login/verify?token=<token> to complete
sign-in. Dev-only — this reads the raw token straight out of the local
database and only works because there’s no real mail transport configured
locally; never do this against staging or production.
Prerequisites
- Rust (stable) —
rustup update stable - PostgreSQL running locally
- Redis running locally
- Neo4j running locally (only if
rag.enabledis true; the topic graph needsrag.neo4j_v2) - Whisper model files in
api/transcription_models/(only if using local transcription)
Config
Copy and edit the config:config.yml:
Running the API
Running workers
Workers run as separate processes. Open additional terminals:Whisper models are loaded once at worker startup. The
base model (~1 GB) is sufficient for local dev. Download it with ./api/download-models.sh.Running the web UI
VITE_API_BASE_URL=http://localhost:8000/api in ui/web/.env if the API is on a different port.
Running with Docker Compose
For a quick local setup (API + Redis only — workers run manually):Database migrations
Migrations run automatically on API startup. To run them manually:Useful debug flags
Worker management (production)
On production servers, workers are managed viamanage-workers.sh deployed to /opt/kair-voice-workers/: