{"slug": "show-hn-portmarshal-guard-dev-servers-from-cross-agent-stops", "title": "Show HN: PortMarshal – Guard dev servers from cross-agent stops", "summary": "PortMarshal, a new open-source command-line tool for macOS and Linux, prevents parallel coding agents from accidentally stopping each other's local development servers by mapping TCP listeners to their owning process, project, and agent. The tool, installable via npm, detects port drift, coordinates sticky port claims, and blocks one agent from killing another agent's active service by default. It supports cooperative agents like Claude Code, Cursor, VS Code, and Docker, and requires Node.js 18.17 or newer.", "body_md": "Know which coding agent owns a local dev server — and stop the wrong one from being killed.\n\n**English** | [简体中文](/worsher/portmarshal/blob/main/README.zh-CN.md)\n\nPortMarshal is an agent-aware ownership and safety layer for local development services on macOS and Linux. It maps attributable TCP listeners to their PID, project directory, and launching agent; coordinates sticky port claims; detects port drift; and blocks one agent from stopping another agent's active service by default.\n\n```\nnpm install -g portmarshal\nportmarshal list\nportmarshal whois 3000\n```\n\nThe last command inspects the process, project, and agent behind a dev server already listening on port 3000.\n\nParallel coding agents create three recurring problems:\n\n**Silent drift**— an agent expects port 3000, but the framework silently starts on 3001.** Detached services**— a session exits while its dev server keeps listening.** Friendly fire**— one agent frees a port by stopping another agent's service.\n\nPortMarshal scans first and coordinates second. Existing listeners do not need to be launched through PortMarshal to be discovered. Cooperative agents gain stable claims and stronger ownership signals, while uncooperative services still appear when the operating system exposes their process metadata.\n\n```\nnpm install -g portmarshal\nportmarshal --help\n```\n\nRequires Node.js 18.17 or newer. The runtime has no npm dependencies.\n\n```\nnpm uninstall -g @worsher/portscout @worsher/portmarshal\nnpm install -g portmarshal\n```\n\nOn first use, PortMarshal copies an existing `~/.portscout/registry.json`\n\ninto `~/.portmarshal/registry.json`\n\n, preserving sticky claims without deleting the old data.\n\n| Command | What it does |\n|---|---|\n`portmarshal list [--json] [--all] [--project .]` |\nList listeners with project, source, and state: active, reserved, unregistered, or drift |\n`portmarshal whois [--json]` |\nInspect one port: PID, project directory, full command, agent or service source |\n`portmarshal claim [--prefer N] [--range A-B]` |\nAllocate a cooperative sticky port claim; stdout contains only the port number |\n`portmarshal release ` |\nRelease a claim without stopping its process |\n`portmarshal stop [--force|--gui]` |\nStop a service behind the ownership guard |\n`portmarshal gc [--kill-detached]` |\nReap stale claims and review or stop detached service candidates |\n`portmarshal watch` |\nRefreshing terminal dashboard; press `q` to quit |\n`portmarshal menubar [--install]` |\nSwiftBar menu with guarded click-to-stop actions |\n\nTypical agent startup:\n\n```\nPORT=$(portmarshal claim web --prefer 3000)\nnpm run dev -- --port \"$PORT\"\n```\n\nA claim is a cooperative lease, not an operating-system socket reservation. PortMarshal revalidates a previous claim before reusing it: a port must still be free or be attributable to the same project. There is still an unavoidable handoff window between returning a free port and the application binding it.\n\nPortMarshal follows the process parent chain to identify `claude-code`\n\n, `cursor`\n\n, `antigravity`\n\n, `vscode/electron`\n\n, `terminal`\n\n, `docker`\n\n, and `pm2`\n\n. PM2-managed listeners are enriched from `pm2 jlist`\n\n, displayed as `pm2:`\n\n, and attributed to the application's configured cwd; the full PM2 environment is never retained. For published Docker ports, PortMarshal inspects running-container metadata: shared Docker Desktop listeners are split by container, the source is shown as `docker:/`\n\n, and the host project directory is recovered from Compose, Dev Container, or bind-mount metadata. If managed-runtime metadata is unavailable, attribution safely falls back without inventing ownership. PortMarshal also recognizes `launchd: