Skip to main content

Local Development

Each repo runs independently. Start only the services your task needs (see the slices in New Engineer).

Ports & env

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​

StoreUsed byLocal note
MongoDBbackend, ms-communication, ms-sessionsUse mongo:7.0 — MongoDB 8.0 segfaults on some kernels.
Redisbackend, ms-communication, ms-sessions, ms-aiOne instance is fine locally; the cluster splits per service.
Postgres + pgvectorms-aiProvided by ms-ai/docker-compose.yml (Postgres 17 + pgvector).
S3backend, ms-sessionsReal 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 exposes 8888).
  • Needs MongoDB + Redis. Set MS_AI_URL, MS_SESSION_URL, MS_COMMUNICATION_URL and MS_AI_SECRET_TOKEN to reach peers.
  • SERVICE_CRON=true enables 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=false to stop that while debugging; GET /healthz/db shows the ping and watchdog state.
  • Secrets: without SECRET_ENCRYPTION_KEYS / SECRET_ENCRYPTION_KEY the 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 in credential_keys and 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. Unset FILE_LINK_SECRET (and RECORDING_LINK_SECRET) means private files are only reachable logged-in (signed links fail closed).
  • Optional feature env: PARTNER_HUB_AGENTS_FAKE=on makes the Partner Hub agents use fake API data; OPS_VIDEO_WORKER_KEY enables the ops "Run on my PC" worker routes, and node scripts/release-worker/worker.mjs runs the release worker against WORKER_API (default http://localhost:4011); SERVICE_VIDEO=true makes a pod render product-update videos (needs Chromium + ffmpeg, CHROME_PATH). Outside production every product-update email goes only to PRODUCT_UPDATES_TEST_TO.
  • Tests: npm test (mocha, entry test/index.test.js). Real-Mongo checks that can't run in prod live in scripts/ (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 optionally MISTRAL_API_KEY, COHERE_API_KEY for rerank, ELEVENLABS_API_KEY for 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 test needs 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:

  1. Mongo + Redis up.
  2. backend (SERVICE_CRON=false), ms-sessions (+ recording worker), ms-communication.
  3. widget pointed at local backend.
  4. Optionally frontend to watch the session live and answer chats/calls.

Add ms-ai (+ Postgres) only when you need AI chat/voice or Nox.