persistent-localhost
/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.
- Author
- davidondrej ↗
- Repository
- skills ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/persistent-localhost.sh
What it does and when to use it
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.
Original author 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.
How it works
- Workflow
- Hot reload
- Rules the script enforces
- Fallback
SKILL.md preview
--- 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: ```bash 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. ```bash 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: ```bash 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.
Files in this package (2)
- SKILL.md 2 KB
- scripts/persistent-localhost.sh 7 KB
Versions
The database has no other skills named persistent-localhost.
Database snapshot: 13.11.2026 · package version be3d707e1170 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100previewctl
Start, inspect, and stop local web previews and development servers on Windows, macOS, and Linux through previewctl. Use for localhost previews, Vite or Next.js dev servers, static HTTP servers, preview URLs, logs, and cleanup; not for production deployment or remote hosting. - 100managing-astro-local-env
Manage a local Astronomer/Airflow environment with Astro CLI. Use when the user says astro dev start/stop/restart, local scheduler, astro dev parse, astro dev pytest, local task logs, localhost Airflow UI, or Makefile wrappers like make airflow / make scheduler-restart. Not for… - 100pitchfork
Manage Speakeasy's local development services (server, worker, dashboard, streams, etc.) with pitchfork — start/stop/restart daemons, check health, and query their logs. Activate whenever you need to bring up the local dev stack, restart a service after a code change, check… - 100deployhq
Deploy code, manage servers, and automate infrastructure via the DeployHQ CLI (dhq). Use when the user wants to deploy, check deployment status, manage projects/servers, or interact with the DeployHQ platform. - 95managing-astro-local-env
Manage local Airflow environment with Astro CLI (Docker and standalone modes). Use when the user wants to start, stop, or restart Airflow, view logs, query the Airflow API, troubleshoot, or fix environment issues. For project setup, see setting-up-astro-project. - 95railway-deployment
Manage Railway deployments - view logs, redeploy, restart, or remove deployments. Use for deployment lifecycle (remove, stop, redeploy, restart), deployment visibility (list, status, history), and troubleshooting (logs, errors, failures, crashes). NOT for deleting services - use…