@lensmcp/cluster

Run your Nx workspace as a local, production-shaped cluster — backend pods on unix sockets with true HMR, behind ONE HTTPS gateway with per-project domains, scale-from-zero, autoscale, idle-kill, and local-CA TLS.

@lensmcp/cluster is the Nx plugin behind LensMCP, an observability lens for coding agents. It turns a monorepo of NestJS services and frontend apps into a cluster that behaves like production on your laptop: each backend service runs N hot-swappable child processes ("pods") on unix sockets with real NestJS HMR (20–100ms edit loop, in-memory state preserved), and a single HTTPS gateway routes traffic to them by hostname — app.tetros.ai.local, api.tetros.ai.local, and so on — over a locally-trusted CA so HTTPS just works.

The point is parity. The same gateway routing core (matchRoute / buildRouteTable) runs in dev and in production, so what you exercise locally — per-domain routing, path-mounted microservices, scale-from-zero, edge JWT verification + ABAC, and weighted / attribute-based rollout — is the same shape that ships. In dev the gateway runs on node:http + http-proxy (it owns the unix-socket pods and their lifecycle); in production the same routing brain is composed over a Fastify + @fastify/reply-from (undici) transport, shipped as a Node 26 distroless image for the high-RPS edge. Throughout, the cluster publishes to the LensMCP event bus (service up/down, cold starts, autoscale, idle kills, request-derived traffic edges) so the dashboard can draw your live topology.

Install

It's a dev-time Nx plugin:

yarn add -D @lensmcp/cluster

Peer dependencies @nx/devkit, @nx/webpack, and webpack are required. fastify, @fastify/reply-from, and ioredis are optional peers — install them only if you run the production gateway (Fastify/undici) and/or its Redis-backed registry.

The cluster field

A project opts into the cluster by adding a top-level cluster block to its project.json. The gateway scans every project in the workspace, reads these declarations, and synthesizes the route table from them. (The legacy field name davnx is still read for back-compat.)

A backend NestJS service in pod / socket-pool mode:

{
  "name": "api",
  "cluster": {
    "host": "api.tetros.ai.local",  // public dev hostname (TLS SAN added automatically)
    "service": "api",                // socket-pool mode: round-robin the devserver's pods
    "minPods": 1,                     // spawn this many; autoscale up to maxPods
    "maxPods": 4,                     // ceiling while requests overlap
    "idleKillSec": 120,               // kill a scaled-from-zero service after N idle seconds
    "eager": false                    // false (default) = start on first request (scale from zero)
  },
  "targets": { "serve-hmr": { "executor": "@lensmcp/cluster:serve", "options": { "childCount": 1 } } }
}

A frontend app (Vite, etc.) in TCP / upstream mode, claiming the root domain as the catch-all:

{
  "name": "dashboard",
  "cluster": {
    "host": "app.tetros.ai.local",
    "port": 5173,        // shorthand for upstream: http://localhost:5173
    "default": true      // also serves any unmatched hostname
  }
}

A second backend path-mounted under a shared API domain:

{
  "name": "crm",
  "cluster": {
    "host": "api.tetros.ai.local",  // same host as `api`...
    "path": "/crm",                  // ...but mounted under a path prefix
    "service": "crm",
    "prependPrefix": "/crm"          // forward to the service at /crm/... (prod parity)
  }
}

Fields

| field | meaning | | --- | --- | | host | Public dev hostname (e.g. api.tetros.ai.local). A TLS SAN is added for it automatically. | | path | Mount path under host — lets multiple backends share one domain (host+path routes outrank host-only). | | service | Socket-pool (pods) mode: the cluster devserver's service name. The gateway round-robins directly over its children's unix sockets — one load balancer in front of N pods, like prod. Pod services also auto-expose internal.<host> for east-west calls that skip the gateway middleware (the JWT seam). | | upstream | TCP mode: full URL where the dev server listens (e.g. a Vite app). | | port | Shorthand for upstream: http://localhost:<port>. | | prependPrefix | Prepend to forwarded URLs — serve a prefix-mounted service at the root of its own dev domain (prod parity). | | default | This project is the catch-all for unmatched hostnames. | | internalHost | Override the auto internal.<host> name, or false to disable the internal route. | | auth | Edge auth policy: { default, overrides } (JWT verify + identity injection + per-path ABAC enforcement). Absent ⇒ unguarded at the edge. Typically generated from controller decorators rather than hand-written. | | eager | true = start at gateway boot; false (default) = start on first request (scale from zero). | | minPods / maxPods | Pod range: spawn minPods, autoscale up to maxPods while requests overlap. | | idleKillSec | Kill a gateway-spawned (non-eager) service after this many idle seconds. | | serveTarget | Nx target that runs the service. Default serve-hmr. | | adminUrl | Devserver admin endpoint for scaling (defaults from port). |

A declaration must route somewhere: either a pod service or a TCP upstream/port.

Executors

| executor | purpose | key command | | --- | --- | --- | | @lensmcp/cluster:serve | Webpack watch + integrated devserver running a pod pool of NestJS children (true HMR). | nx run api:serve-hmr | | @lensmcp/cluster:gateway | The workspace HTTPS front door — reads every project's cluster field, routes by hostname, serves the local-CA cert with all SANs. | nx run gateway:serve | | @lensmcp/cluster:trust | One-time local HTTPS setup: trust the local CA in the OS keychain + write /etc/hosts entries (127.0.0.1 + ::1) for every gateway hostname. Idempotent. | nx run gateway:trust | | @lensmcp/cluster:build | Production webpack build for a NestJS app. | nx run api:build |

(Target names like serve-hmr / gateway are conventions; the executor is what matters.)

Key options

serve — entryFile, tsConfigFile (required); childCount (pods in the pool); internalPort (plain-HTTP listener straight to children, no gateway middleware — for service-to-service calls); workers (extra entry bundles compiled in watch mode); servePrefix, serviceName, configEnv; orgScopes / bundlePackages / nodeExternalsConfig (control what's bundled vs externalized); an embedded gateway block (middleware, routes, https, extraPorts) for single-service setups.

Pass minPods via the --childCount option — the Nx daemon drops spawner env, so don't pin childCount in serve-hmr options expecting minPods to flow through.

gateway — ports (default [443] so dev domains need no :port); https (default true, terminate TLS with the local CA); middleware (workspace-relative JS module (req) => void run on every request — the JWT/auth seam; throwing rejects with 401); trafficFlushMs (traffic-edge aggregation window before flushing to the LensMCP bus; default 5000).

trust — serveTarget (whose gateway.routes hostnames to set up, default serve-hmr); hosts (extra hostnames to add to /etc/hosts).

build — entryFile, tsConfigFile (required); outputPath, assets, workers; generatePackageJson; runtimeDependencies; migrationsDir / ormConfigPath; the same bundling controls as serve.

Gateway

One front door, two transports sharing one routing brain:

• Routing — every cluster declaration becomes a route; requests match by hostname (exact beats *.suffix wildcard) then by most-specific path prefix. A claimed host's unmatched root is served by the gateway itself (/health aggregate, /.well-known/..., CORS + preflights); an unclaimed host can only reach the default route or 404.
• Dev transport — node:http + http-proxy. It owns the unix-socket pods: scale-from-zero on first request, autoscale while requests overlap, idle-kill, supervised reforks, and ghost-socket sweeping.
• Prod transport — the same matchRoute composed over Fastify + @fastify/reply-from (undici) (connection-reusing, HTTP/1.1 pipelined; benchmarks materially lower CPU/req than http-proxy), shipped as a Node 26 distroless image. No process management — prod pods are always-on (k8s keeps them up).
• Edge auth + identity — for jwt routes the gateway verifies the end-user token (dev: HS256 shared secret; prod: RS256 via JWKS) and stamps trusted identity headers (x-user-id, x-tenant-id, roles, perms) onto the forwarded request; internal.<host> routes require x-api-key. Per-path ABAC rules (a permission or full predicate over verified claims + IP/headers, scoped by HTTP method) are enforced at the edge → 403.
• Rollout — per-request upstream selection supports weighted cohorts (smooth nginx-style split for canary / blue-green) and attribute-based targeting (route by user / tenant / IP / header / sticky device key, consistent-hashed so a ramp moves a key across the boundary at most once). The serving version rides on x-lensmcp-version and the trace.

How it fits

@lensmcp/cluster is one library in the LensMCP workspace:

• lensmcp — the lens / observability dashboard that renders the live cluster topology the gateway publishes.
• @lensmcp/node-instrumentation — zero-touch Node instrumentation injected into each pod (the host source stays lens-free); it feeds the events (egress, db/redis/queue ops, NestJS class traces and request flows) the dashboard correlates with the gateway's traffic edges.

Part of LensMCP. Apache-2.0.