Knowledge Vault

Sea Captain Port Management

2 min read

Sea Captain Port Management

Problem

Running multiple apps simultaneously in a solopreneur dev environment causes port collisions. Reactive approaches (finding and killing conflicting processes) don’t scale.

Solution

The “Harbor Master” architecture: a proactive system where conflicts are designed out rather than debugged away.

Pattern Components

1. Harbor Master (Reverse Proxy)

Stop accessing apps via localhost:PORT. Use a local reverse proxy that maps names to ports:

  • Tools: Traefik or Caddy (cloud-native, auto-detect containers)
  • Workflow: Start App A, proxy routes http://app-a.localhost automatically
  • Benefit: Never remember a port number again; subdomain isolation prevents cookie/CORS bugs

2. Ship’s Log (Static Port Registry)

Single Source of Truth file assigning dedicated port blocks per project:

Project "Nautilus": 3000-3009 (Web: 3000, API: 3001, DB: 3002)
Project "Kraken":   3010-3019 (Web: 3010, API: 3011, DB: 3012)
Project "Siren":    3020-3029

Hardcode into .env files. Eliminates 99% of conflicts proactively.

3. Tugboats (Process Management)

Use a process manager instead of multiple terminal tabs:

  • Overmind (recommended) — Uses Procfile, handles output multiplexing
  • Puma-dev (macOS) — Zero-config .test domains with local HTTPS

4. Sea Captain CLI

Shell functions for the remaining edge cases:

  • check_port <port> — lsof -i :<port>
  • sink_ship <port> — Kill process on port
  • radar — Show all listening ports

Assessment of Approaches

StrategyGradeNotes
Default standards (3000, 8000)B-Guarantees collisions with multiple apps
Kill conflicting processesC+Reactive “whack-a-mole”
Reverse proxyAGold standard — decouples internal port from access
Subdomain isolationA+Essential for cookies, CORS, multi-tenancy
AI agents for port detectionDOverkill — use a 5-line bash script instead

Implementation in Aloysius Productions

The port registry lives at ops-core/shared-resources/ship-log/ports.yaml with the Sea Captain CLI at ops-core/shared-resources/sea-captain/sea-captain.sh.

Graph View

Backlinks