A single source of truth for service ports.
Agents read it before starting services. Humans edit it when things change.
AI coding agents spin up dev servers, APIs, databases, and proxies. They pick ports -- often the same default ports (3000, 5173, 8000, 8080). Two agents working on different projects can collide. Two agents working on the same project definitely will.
PORTMASTER.md is the answer. It's a machine-readable, human-maintainable registry of every port on a machine. Agents check it before binding. Humans update it when they add or move a service.
- You create a PORTMASTER.md in your agent rules directory (or repo root).
- You configure your agents to read it at session start.
- Every time a service is added, moved, or removed, the file gets updated.
- Agents consult it before
npm run dev,docker compose up,python -m http.server, etc.
No daemon. No port scanner. Just a Markdown file that agents already know how to read.
Add this to your global agent rules (~/.config/agent-rules/GLOBAL.md or equivalent):
## Port Management
- **PORTMASTER.md:** Before starting any service, read `PORTMASTER.md` in the
active project root (or `~/.config/agent-rules/PORTMASTER.md` as fallback).
Check for port conflicts. Update the file when you bind a new port.Add to .cursorrules:
Before starting any dev server or binding a port, check PORTMASTER.md for conflicts.
Update PORTMASTER.md when you add, move, or remove a service.
Same idea -- reference PORTMASTER.md in whatever rules/config mechanism your agent uses.
# Copy the template to your agent rules directory
cp PORTMASTER.md.template ~/.config/agent-rules/PORTMASTER.md
# Or drop it in a specific project
cp PORTMASTER.md.template ~/my-project/PORTMASTER.mdThen populate it with your actual services:
# See what's running right now
lsof -iTCP -sTCP:LISTEN -P -n | grep LISTEN | sort -t: -k2 -nPORTMASTER.md has three sections:
| Section | Purpose |
|---|---|
| Active Services | Table of every bound port -- what it is, who owns it, any notes |
| Port Allocation Ranges | Agreed-upon ranges so new services don't clash |
| Conflicts & Caveats | Known pain points: Docker vs API, Vite vs Vite, etc. |
See the template for the full annotated version.
MIT -- use it, fork it, ship it with your agent rules. No attribution required.