Skip to content
Skills Library
DevOps & cloud · Automation

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.

Repository
skills ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Workflow
  2. Hot reload
  3. Rules the script enforces
  4. Fallback
Original SKILL.md headings · 46 lines, 295 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.