Local Development
Each repo runs independently. Start only the services your task needs (see the slices in New Engineer).
Ports below are the observed defaults; the source of truth is each repo's .env
and config. Always copy the repo's example env and fill in secrets before
starting.
Shared data stores
| Store | Used by | Local note |
|---|---|---|
| MongoDB | backend, ms-communication, ms-sessions | Use mongo:7.0 — MongoDB 8.0 segfaults on some kernels. |
| Redis | backend, ms-communication, ms-sessions, ms-ai | One instance is fine locally; the cluster splits per service. |
| Postgres + pgvector | ms-ai | Provided by ms-ai/docker-compose.yml (Postgres 17 + pgvector). |
| S3 | backend, ms-sessions | Real bucket or a local S3-compatible store; FILE_STORAGE=local skips S3. |
Node services
All Node services target Node 20+ (containers run Node 22).
backend (Express / Nodevel)
cd backend
npm install
npm run dev # nodemon
- Default app port
8080(container exposes8888). - Needs MongoDB + Redis. Set
MS_AI_URL,MS_SESSION_URL,MS_COMMUNICATION_URLandMS_AI_SECRET_TOKENto reach peers. SERVICE_CRON=trueenables the scheduler (cron jobs). Leave it off for a normal API dev loop; the production scheduler runs as a separate pod.- The MongoDB watchdog exits the process after 5 failed pings (~2.5 min) — if
your local Mongo is down, nodemon will keep restarting the app. Set
MONGO_WATCHDOG_ENABLED=falseto stop that while debugging;GET /healthz/dbshows the ping and watchdog state. - Secrets: without
SECRET_ENCRYPTION_KEYS/SECRET_ENCRYPTION_KEYthe backend uses a fixed dev key (production refuses to boot). If you point a local backend at a database that already holds vault secrets written with another key, the first pod to use it records that key's fingerprint incredential_keysand any pod with a different key refuses to read or write secrets ("Encryption key … differs"). Use one key per database, and keep ms-communication on the same key. UnsetFILE_LINK_SECRET(andRECORDING_LINK_SECRET) means private files are only reachable logged-in (signed links fail closed). - Optional feature env:
PARTNER_HUB_AGENTS_FAKE=onmakes the Partner Hub agents use fake API data;OPS_VIDEO_WORKER_KEYenables the ops "Run on my PC" worker routes, andnode scripts/release-worker/worker.mjsruns the release worker againstWORKER_API(defaulthttp://localhost:4011);SERVICE_VIDEO=truemakes a pod render product-update videos (needs Chromium + ffmpeg,CHROME_PATH). Outside production every product-update email goes only toPRODUCT_UPDATES_TEST_TO. - Tests:
npm test(mocha, entrytest/index.test.js). Real-Mongo checks that can't run in prod live inscripts/(e.g.scripts/person-merge-integration.js).
ms-ai (NestJS)
cd ms-ai
npm install
docker compose up -d # Postgres(+pgvector) + Redis
npm run migration:run # apply TypeORM migrations
npm run start:dev # watch mode
- Default port
3000. - Needs
ANTHROPIC_API_KEY/OPENAI_API_KEY(and optionallyMISTRAL_API_KEY,COHERE_API_KEYfor rerank,ELEVENLABS_API_KEYfor voice). - Migrations are not run in the container entrypoint — run them yourself (or via CI) to avoid races across replicas.
ms-communication / ms-sessions (Nodevel)
cd ms-sessions # or ms-communication
npm install
npm run dev
- ms-sessions: app port
3003. Recording worker runs separately:npm run dev:recording-worker.npm testneeds mocha 11 (bumped for Node 26, where mocha 9 can't start); there is no lockfile in this repo. - ms-communication: app port
8080. Needs Twilio / APN / Firebase / Slack creds for the features that use them (mock or leave unset to disable). - Both need MongoDB + Redis.
Client apps
frontend (Vue dashboard)
cd frontend
npm install
npm run dev # Vite dev server on :4000
Point it at your local backend via src/config/env.config.js / VITE_* env.
widget (Vue, embeddable)
cd widget
npm install
npm run dev # Vite dev server
The widget connects to backend / ms-communication / ms-sessions sockets keyed by
company_id + user_session_id. For end-to-end testing, load it against a test
company in your local backend.
desktop (Electron)
cd desktop
npm install
npm run dev # Vite + Electron, hot reload
npm run dev:next # white-label ("Next Level AI") variant
Desktop wraps the same dashboard code as frontend. Do not mirror frontend
edits into desktop per-PR — desktop is synced at release time (see
Conventions).
Putting it together
A typical "visitor end-to-end" loop:
- Mongo + Redis up.
backend(SERVICE_CRON=false),ms-sessions(+ recording worker),ms-communication.widgetpointed at local backend.- Optionally
frontendto watch the session live and answer chats/calls.
Add ms-ai (+ Postgres) only when you need AI chat/voice or Nox.