Finding
Local Hermes development becomes fragile when dev-server startup assumes the default port is free instead of treating port ownership as a preflight check.
Current
A real Hermes installation often uses local dashboards, test servers, docs previews, gateway tooling, or frontend development servers during configuration and debugging. The weak point is that port conflicts are usually discovered only after a failed start, ambiguous browser behavior, or a second server silently choosing a different port. That creates avoidable confusion: the operator may debug the app, config, proxy, or credentials when the real issue is simply an existing process already bound to the expected port.
Suggested
- Add a dev-server port preflight to the local runbook. Exact change: update
docs/runbooks/local-dev-server.mdor the project setup notes with a required first step: check whether the intended port is already listening, identify the owning process, and decide whether to stop it, reuse it, or move the new server to a documented alternate port. - Make port assumptions explicit in development prompts and scripts. Exact change: patch the main development skill or
SOUL.mdwith: “Before starting a local Hermes dashboard, docs preview, API server, or frontend dev server, verify the target port and report the process owner if it is occupied.” - Add a post-start verification habit for browser-facing work. Exact change: add a checklist item to the UI/debugging runbook or dashboard copy: after server start, verify the actual bound URL, confirm it matches the expected port, and record any alternate port in the task summary before testing routes or screenshots.
Impact
This reduces false debugging trails during local Hermes work. Operators can distinguish “the app is broken” from “the port is already occupied” before spending tokens or time on the wrong layer. It also makes browser testing and dashboard verification more reliable because every test starts from a confirmed server endpoint.
Effort
Small — this is a runbook, prompt, and verification habit change. No new infrastructure is required; the value comes from making port ownership visible before starting or testing dev servers.
Public page note
Safe public content includes the operational pattern, generic port-conflict checks, development-runbook recommendations, and the maturity benefit of preflight verification. Internal-only content includes actual process lists, local hostnames, private URLs, raw terminal output, logs, environment values, credentials, filesystem paths, and any live service details from a specific installation.