Home

warden

Nothing binds a port without asking.

One place that decides which local port a service runs on. Services register under a name, say what they are, and get a port back. The same name keeps the same port across restarts, so a backend never wakes up on the port its frontend grabbed while it was down.

$ warden run -- npm run dev
shop-api  ->  8000

It is also useful without any of that: warden ports shows what is listening on a machine and warden kill 3000 frees a port. Neither needs a server running anywhere.

Start here

Page	For
Installation	Getting the warden command
One machine	The usual setup: a registry for your own projects
Ports and processes	Seeing and freeing ports, no server needed
Python client	Asking for a port from your own code
Cluster	Several machines, one hub that knows them all
Docker	The image, a compose file, and what a container can see
Updates	Knowing a new version is out, and rolling it across a fleet
Configuration	Every setting there is
Command line	Every command and flag
HTTP API	Endpoints, payloads, status codes
Troubleshooting	When something does not behave

The idea

On a machine running a handful of projects, ports get picked by hand and written down in three places: a .env, a vite.config.ts, and someone's memory. Two services eventually pick 8080, and the second one fails to start — or worse, starts and talks to the wrong neighbour.

warden replaces that with a registry:

• a service asks for a port instead of hardcoding one
• ports come from one pool, so two services cannot collide
• a service keeps its port across restarts
• ports occupied by something outside the registry are skipped, because warden tries to bind a port before handing it out
• warden ls answers "what is on 8003?"
• warden history 8003 answers it for last week, after the service is gone

Two things, worth telling apart

The registry is warden's own book: who asked, and what they were given. warden ls reads it. It only knows what went through warden.

The listeners are what the operating system reports as bound right now, whether warden handed it out or not. warden ports reads that.

Having both is what makes a stranger on a port visible: warden ports marks every socket that came from the registry, so anything unmarked arrived some other way.

Where things live

Repository	https://github.com/vxnsin/warden
Registry database	%LOCALAPPDATA%\warden\registry.db on Windows, ~/.local/share/warden/registry.db on Linux
Default address	http://127.0.0.1:7010
Default pool	8000-8999