PM2 Cluster Mode: Scale Node.js Across All Cores

Why it exists

Node.js is famously single-threaded. On a server with multiple CPU cores, a standard Node process uses only one, wasting the rest of the machine's power. PM2's cluster mode was created to easily utilize all available CPU power for a single application, dramatically increasing its performance and reliability without code changes.

The mental model

Think of your Node.js app as a single cashier. Cluster mode doesn't make that cashier faster; it opens new checkout lanes, one for each CPU core, with a clone of your app at each one. All clones serve different customers simultaneously, but they all use the same backend systems, like a shared database for state. This multiplies the number of customers you can serve at once.

How it works

Under the hood, cluster mode uses the native Node.js cluster module. When you run pm2 start app.js -i max, PM2 creates a primary process that forks multiple 'worker' processes, one for each CPU. This primary process listens on your app's port and distributes incoming connections to the workers, typically in a round-robin fashion. This allows multiple instances of your app to handle requests concurrently on the same port.

When to use it

Use cluster mode for any networked Node.js application, like an Express API or other HTTP/TCP server, running on a multi-core machine. It's the standard first step for vertical scaling on a single server. It also enables zero-downtime reloads using pm2 reload, which restarts workers one by one instead of killing the whole app at once.

When not to use it

Do not use cluster mode if your application is stateful. Each worker is an isolated process with its own memory. If you store user sessions or WebSocket connections in a worker's memory, a user's next request could be routed to a different worker that has no knowledge of that state, breaking the user experience. All shared state must be externalized to a database, Redis, or another shared service.

One canonical example

To scale an API server named api.js across all available CPU cores, the command is pm2 start api.js -i max. In a configuration file, you would set exec_mode: "cluster" and instances: "max". For a zero-downtime update, you would run pm2 reload api. This ensures continuous service availability by restarting each worker sequentially.