Run the platform locally
Run the API, messaging, media, console, playground and docs on your machine.
Prerequisites
Use the Node version in .nvmrc, pnpm 12.18.0, Git, Bash, jq and Docker with Compose. The lockfile pins dependency resolution. Linux supports the complete container-based test stack. On macOS/WSL, use native LiveKit for browser media or use staging; Docker NAT can advertise unusable ICE addresses.
npm install --global pnpm@12.18.0
pnpm install --frozen-lockfile
cp .env.example .env
pnpm --filter @lynkoria/api exec tsx scripts/gen-secrets.ts --write ../../.env
docker compose --env-file .env -f infra/local/compose.yaml --profile livekit --profile attachments up -d --wait
pnpm db:migrate
pnpm db:seedgen-secrets.ts --write fills the secrets into .env in place and keeps values that are already set, so running it again is safe. Do not append its output to .env with >>: .env.example already lists those keys, and a second, different set makes service keys minted under one pepper fail under the other ("Invalid service key").
db:seed is for development only. It creates an organization with ADMIN_DEV_EMAIL as owner (so the console stops answering "No console role assigned") and three sample projects, and prints their service keys once. Copy each key in full; it ends with letters, digits, - or _. If a key is lost, create another staging key in the console (Projects → project → API keys).
Where the local apps read their service key:
| App | File (gitignored) | Variables |
|---|---|---|
Playground (apps/playground) | .env at the repository root | PLAYGROUND_SERVICE_KEY |
Next.js example (apps/example-nextjs) | apps/example-nextjs/.env.local | LYNKORIA_API_URL=http://localhost:3001, LYNKORIA_SERVICE_KEY |
TanStack Start example (apps/example-tanstack-start) | apps/example-tanstack-start/.env.local | same as Next.js |
Each browser origin must be allowed: add http://localhost:3100 (Next.js) and http://localhost:3200 (TanStack Start) to ALLOWED_ORIGINS before seeding, or to the project environment's allowed origins in the console afterwards. Restart pnpm dev (and pnpm dev:example) after changing these files: the playground and TanStack Start read them only at startup (Next.js reloads .env.local itself). Never run the demo backend in production.
pnpm dev| Component | Local address |
|---|---|
| Playground | http://localhost:5173 |
| Admin console | http://localhost:5174 |
| API | http://localhost:3001 |
| Documentation | http://localhost:3002 |
| LiveKit signaling | ws://127.0.0.1:7880 |
pnpm dev does not start the example apps. With it running, start them in a second terminal:
pnpm dev:example| Example | Local address |
|---|---|
| Next.js example | http://localhost:3100 |
| TanStack Start example | http://localhost:3200 |
The local console impersonates ADMIN_DEV_EMAIL; production explicitly rejects this setting. The playground’s server holds the service key and issues user tokens. Two browser profiles provide two separate demo users.
Verify the stack
curl --fail http://localhost:3001/health/ready
pnpm check
pnpm buildTests create and migrate a separate _test database. The local PostgreSQL user must be allowed to create it. Never point integration tests at production. See local development for port overrides and targeted checks.
Open a conversation in two profiles, exchange messages, refresh and check history. Create a call and enable microphone/camera in both profiles. The automated tests cover control-plane integration; they do not replace real audio/video, mobile-network or TURN checks.
First product integration
Create a project and staging environment in the console, select a configured LiveKit key reference, enable messaging/presence if needed, and allow your exact browser origin. Issue a scoped service key. Store it only in your product backend, then follow authentication and SDK usage.