Skip to Content
LYNKORIADocs

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:seed

gen-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:

AppFile (gitignored)Variables
Playground (apps/playground).env at the repository rootPLAYGROUND_SERVICE_KEY
Next.js example (apps/example-nextjs)apps/example-nextjs/.env.localLYNKORIA_API_URL=http://localhost:3001, LYNKORIA_SERVICE_KEY
TanStack Start example (apps/example-tanstack-start)apps/example-tanstack-start/.env.localsame 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
ComponentLocal address
Playgroundhttp://localhost:5173
Admin consolehttp://localhost:5174
APIhttp://localhost:3001
Documentationhttp://localhost:3002
LiveKit signalingws://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
ExampleLocal address
Next.js examplehttp://localhost:3100
TanStack Start examplehttp://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 build

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

On this page