portman 1.0.0

Port manager for containerised development on macOS, Linux, and Windows

portman — Port Manager for containerised development

Engineered by Codermasky

A global port registry and conflict-free port assignment system for all your Docker Compose projects on macOS, Linux, and Windows.

---

Quick Start

bash ~/Sandbox/portman/install.sh
source ~/.zshrc
portman new myproject
portman list

---

Files

• portman.py — Main CLI tool (Python 3.7+)
• install.sh — One-time installation script
• GUIDE.md — Complete user guide with examples and troubleshooting

---

What It Does

Problem: Running 15+ projects in ~/Sandbox, each with docker-compose, and manually tracking which ports are in use? Constant conflicts.

Solution: portman auto-assigns ports from predefined ranges and prevents collisions:

portman new myapp        # Auto-assigns: frontend:3000, backend:8000, postgres:5432, redis:6379, langfuse:3200
portman list             # View all assigned ports across all projects
portman check            # Detect conflicts (should never happen)
portman scan             # See what's actually listening on your Mac/Linux/WSL2
portman export myapp     # Copy-paste docker-compose ports snippet

---

Installation

cd ~/Sandbox/portman
bash install.sh
source ~/.zshrc    # or ~/.bashrc, ~/.bash_profile, etc.

Then:

portman --help
portman new myproject

---

Port Ranges

Service	Range	Purpose
frontend	3000–3099	React, Vue, Next.js, Vite
backend	8000–8099	FastAPI, Node.js, Flask, Django
postgres	5432–5532	PostgreSQL databases
redis	6379–6479	Redis cache
langfuse	3200–3299	Langfuse observability
clickhouse	8123–8222	ClickHouse analytics
minio	9000–9099	MinIO object storage
grafana	3300–3399	Grafana dashboards

---

Full Documentation

Read the complete guide:

cat ~/Sandbox/portman/GUIDE.md

Or open in your editor:

code ~/Sandbox/portman/GUIDE.md

---

Registry Location

All port assignments are stored in:

~/.portman/registry.json

This is a global file shared across all projects, persists across terminal sessions, and is auto-created on first run.

---

Cross-Platform Support

• macOS — ✅ Full support (uses lsof)
• Linux — ✅ Full support (uses lsof)
• Windows (WSL2) — ✅ Full support
• Windows (native) — ⚠️ Basic support (uses netstat)

Recommended: Use WSL2 on Windows for the best experience.

---

Common Commands

portman list               # Show all ports
portman new myapp          # Create new app with standard services
portman assign svc --app myapp    # Add a service
portman release svc --app myapp   # Remove a service
portman check              # Detect conflicts
portman scan               # See what's listening
portman export myapp       # Get docker-compose snippet
portman rm myapp           # Delete entire app
portman dashboard          # Open visual dashboard in browser

---

Getting Help

portman --help             # Show all commands
portman list --help        # Help for specific command
cat ~/Sandbox/portman/GUIDE.md   # Full guide

---

Why portman?

✅ No more port conflicts — Auto-assign + enforcement ✅ Works across all projects — Global registry at ~/.portman/ ✅ Copy-paste ready — portman export myapp → docker-compose snippet ✅ Cross-platform — macOS, Linux, WSL2, Windows ✅ Zero config — Just portman new myapp and go ✅ Live scanning — portman scan shows what's actually listening

---

Engineered with ❤️ by Codermasky