---

name: persistent-localhost description: "Manage persistent dev servers, APIs, and other local processes on a port using macOS LaunchAgents. Use when starting, stopping, restarting, inspecting, or troubleshooting local servers that should survive shell exit and restart after crashes."

Persistent localhost servers (macOS launchd)

One script does everything. Resolve scripts/persistent-localhost.sh relative to this SKILL.md, never from the current directory.

Workflow

1. Check what already exists:

scripts/persistent-localhost.sh list

2. Start the server. --name is the handle. --port enables readiness checks and duplicate handling. --dir defaults to the current directory.

scripts/persistent-localhost.sh start --name myproj --port 5111 --cmd "./bin/serve"

The command returns only after the port is listening, or fails with the last 20 log lines. Report the printed URL= to the user.

3. Inspect, restart, read logs, stop:

scripts/persistent-localhost.sh status myproj
scripts/persistent-localhost.sh restart myproj   # after editing code that has no reloader
scripts/persistent-localhost.sh logs myproj 100
scripts/persistent-localhost.sh stop myproj

Hot reload

Prefer the framework's own reloader in --cmd (flask run --debug, vite, uvicorn --reload, node --watch). If the server has none, add --watch. It wraps the command in watchexec -r on the working directory. Never use both. Requires brew install watchexec.

Rules the script enforces

• Runs as com.persistent-localhost.<name> in the user gui domain via launchctl bootstrap. Restart uses kickstart -kp, stop uses bootout. No deprecated load, start, stop, no broad pkill.
• KeepAlive only on crash. A clean exit stays down. Throttle 5s so a syntax error cannot spin.
• Port already taken by the same app (our own label, or a stray process with the same working directory) is replaced. A different app is left alone and the next free port is used. Read the printed PORT=.
• The caller's PATH and a PORT variable are passed into the job. Add more with --env KEY=VAL.
• Logs: ~/Library/Logs/persistent-localhost/<name>.log. State: ~/Library/Application Support/persistent-localhost/<name>.state. Plist: ~/Library/LaunchAgents/.

Fallback

Never start servers with nohup, &, disown, setsid, or run_in_background. If launchctl bootstrap fails, report the failure and stop.