Local Dev Clusters

A Local Dev Cluster is a fully-featured ModStack Cluster that runs entirely on a developer's own machine. It exists to give developers the same runtime they will see in production — without leaving their laptop, and without competing with teammates for shared infrastructure.

Built for the developer machine

Dev Clusters allow developers to run a similar configuration to production on their own developer machine. This is extremely useful for debugging inter-service failures. The Telepresence integration also makes this much easier.

Local Dev Clusters are aimed squarely at the inner-loop debugging workflow: edit, run, debug, repeat. They are not multi-tenant, not networked to teammates, and not intended to host anything that matters outside the developer's own workstation.

A Local Dev Cluster is only ever reachable from the machine it is running on. There is no public endpoint and no path for outside traffic to reach it — it is a private sandbox by design.

Full production parity

The single most important property of a Local Dev Cluster is feature compatibility with the production Kubernetes Cluster you would deploy to. Anything that runs in production should run locally the same way:

• The same Service definitions, image builds, and rollout behavior.
• The same Modules, including authentication, storage, and messaging.
• The same ingress, service discovery, and secret-injection semantics.
• The same observability surface — logs, metrics, and traces — so debugging tools work locally exactly as they do in prod.

This means you can reproduce production behavior, including the Modules your app relies on, without spinning up cloud infrastructure or waiting for a shared environment to be free.

Debugging with Telepresence

Local Dev Clusters are optimised for the debugging scenario. The most common case is this: you have a handful of Services running together, and you want to step through just one of them in a debugger without rebuilding the whole stack.

ModStack provides a Telepresence function that does exactly this. You select a single Service, and ModStack redirects its traffic to a process running under your debugger — IDE, breakpoints, hot-reload, everything. The rest of the Services continue to run normally inside the Cluster and talk to your local process as if it were the deployed one.

The result is that you get the convenience of an IDE-driven workflow on a single Service while the rest of the system behaves like a real, fully-wired ModStack environment.

Start and stop on demand

A Local Dev Cluster does not need to be running all the time. You can stop it when you are done for the day or moving between tasks, and start it again when you come back. Stopping it releases the CPU, memory, and disk that the Cluster consumes on your machine — useful when your laptop is also running a browser, an IDE, and everything else.

Because state is preserved between starts and stops, picking back up is fast: your Services come back in the same configuration, with the same Modules attached.

Multiple Local Dev Clusters

You can run more than one Local Dev Cluster on the same machine. Each one is isolated from the others, so it is reasonable to keep separate Clusters per product, per Environment, or per feature branch you are working on.

Only the Clusters you are actively using need to be running. Stop the ones you are not, start the one you are, and your machine only pays the cost of the work in front of you.

Trade-offs

A Local Dev Cluster is not a quick-loop development solution. Builds still run remotely, and a full Service deployment has to run to get your changes onto the Cluster — so the edit-to-running cycle is not as instantaneous as a pure local hot-reload. Telepresence is what bridges this gap for the Service you are actively debugging.

It is also worth understanding how a Local Dev Cluster differs from a Single Node Cluster — both run on a single machine, but they are built for very different purposes: