PortMarshal

Parallel coding agents do not coordinate the local development services they start. One session expects port 3000 but silently moves to 3001, another leaves a server running after it exits, and a third may kill the wrong process while trying to free a port.

PortMarshal is an open-source ownership and safety layer for local development services on macOS and Linux. It shows what is listening, where it came from, and whether it is safe to stop.

What PortMarshal Does

• Attributes local services: Maps visible TCP listeners to their PID, project directory, redacted command, and launching agent or service.

• Prevents cross-agent “friendly fire”: Blocks a stop when the target belongs to another active project or its ownership cannot be safely verified. An explicit --force option remains available after review.

• Works with existing listeners: Services do not need to be launched through PortMarshal first. It scans processes already running on the machine whenever the operating system exposes enough metadata.

• Coordinates stable ports: Sticky claims help agents reuse the same port for the same project and service while detecting silent port drift.

• Manages the complete service lifecycle: portmarshal run claims a port, injects it through PORT or {port}, supervises the command, forwards signals, and releases the claim when the service exits.

• Supports background services: portmarshal run -d captures logs and waits for TCP or HTTP readiness before returning. Failed starts are cleaned up without targeting unrelated processes.

• Understands managed runtimes: Docker/Compose containers and PM2 applications retain their real identity. Stops are delegated to docker stop or pm2 stop instead of signaling shared backends or supervised child processes.

• Protects sensitive output: Common tokens, passwords, authorization headers, cookies, URL credentials, and sensitive query parameters are redacted from displayed commands by default.

Try It in 30 Seconds

npm install -g portmarshal
portmarshal list
portmarshal whois 3000

portmarshal list shows local listeners together with their project and launch source. portmarshal whois 3000 inspects the process, project, and agent or service behind port 3000.

Run a Dev Server Safely

Start and supervise a service in the foreground:

portmarshal run web --prefer 3000 -- npm run dev

Start it in the background and return only when the port is ready:

portmarshal run -d web --prefer 3000 -- pnpm dev
portmarshal logs web -f

PortMarshal recognizes sources including Claude Code, Cursor, IDE and terminal sessions, Docker/Compose, PM2, launchd, and systemd. Detached processes are treated as review signals rather than automatically assumed to be abandoned.

Why Not Just Use lsof?

lsof and ss expose sockets and processes. PortMarshal adds the missing coordination layer: project and agent attribution, sticky claims, drift detection, managed-runtime awareness, and a guarded stop policy.

It is designed for developers running multiple coding agents, worktrees, and local services in parallel without letting one workflow destroy another.

macOS and Linux · Node.js 18.17+ · zero runtime dependencies · MIT licensed

GitHub repository · npm package