Port Allocation

Stackie automatically assigns host ports to each block’s services so they don’t collide. Ports are persisted between runs — restarting a stack gives you the same ports unless a conflict forces reallocation.

How It Works

On first stackie up, Stackie picks free ephemeral ports (49152-65535) for every block service and saves them to ~/.stackie/stacks/{stack}/ports.lock.
On subsequent runs, Stackie bind-tests every saved port. If all are still free, they are reused. If any are taken, all ports are reallocated together to keep cross-block references consistent.

Pinning a Port

To lock a service to a specific port, set it in your stack file:

my-project:
  blocks:
    stackie.postgres:
      serves:
        PORT:
          port: 5432

Any port below the ephemeral range (< 49152) and above zero is treated as pinned — it is never reallocated and always overrides the lock file. Port 0 means “let Stackie pick for me” (the default).

Blast Radius

The ports.lock file only stores port numbers — no secrets. Deleting or corrupting it causes a fresh allocation on the next stackie up but does not affect running processes.