AGENT SKILL

persistent-localhost

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.

License 许可
MIT
所属仓库
davidondrej/skills
最近更新
2026-11-14
Stars
★ 4.3k
Forks
626

01 前言 Front Matter

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.

02 资源文件 1

03 SKILL.md 正文

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
  1. 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.

  1. 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.

04 同仓库更多 Skills