How do I install the Persistent Localhost skill?

Run npx skillmds@latest add davidondrej/persistent-localhost-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Persistent Localhost safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Persistent Localhost?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Persistent Localhost free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Persistent Localhost?

David Ondrej (@davidondrej) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Persistent Localhost by davidondrej

Name: Persistent Localhost
Author: David Ondrej

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.

David Ondrej Updated Sep 21, 2026

File contents

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

Check what already exists:

scripts/persistent-localhost.sh list

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.

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.

---name: persistent-localhost-2description: 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.## Workflow1. Check what already exists:```bashscripts/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.```bashscripts/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:```bashscripts/persistent-localhost.sh status myprojscripts/persistent-localhost.sh restart myproj # after editing code that has no reloaderscripts/persistent-localhost.sh logs myproj 100scripts/persistent-localhost.sh stop myproj```## Hot reloadPrefer 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/`.## FallbackNever start servers with `nohup`, `&`, `disown`, `setsid`, or `run_in_background`. If `launchctl bootstrap` fails, report the failure and stop.

Frequently asked questions