macOS launchd Service Setup

Generate complete launchd service infrastructure for Python applications on macOS.

What This Skill Creates

launchd/
├── install.sh                          # Automated service installer
├── uninstall.sh                        # Service uninstaller
├── {project}.plist.template           # Service configuration
dev.sh                                  # Development mode script
view-logs.sh                           # Log viewing helper

When to Use This Skill

Web services: FastAPI, Flask apps that should auto-start
Background services: Daemons, periodic tasks
Development servers: Local services you want always running

Before Running

Requirements:

macOS 10.10+ with launchd
Python project with uv and .venv
pyproject.toml with [project.scripts] defining a CLI command

Check pyproject.toml:

[project.scripts]
yourapp = "yourapp.cli:main"

Step-by-Step Process

1. Gather Information

You'll need:

Domain (e.g., "dev.pborenstein", "com.pborenstein") - Reverse domain notation for service label
- Default suggestion: dev.{username} (e.g., "dev.philip")
- Best practice: Use owned domain (e.g., "dev.pborenstein" if you own pborenstein.dev)
Project name (e.g., "temoa", "apantli") - lowercase, no spaces
Module name (e.g., "temoa", "apantli") - Python import name
Port number (e.g., 4001, 4000) - unique port for this service
CLI command (e.g., "temoa server", "python3 -m apantli.server")
Dev command (e.g., "temoa server --reload", "python3 -m apantli.server --reload")
Process name (e.g., "temoa server", "apantli.server") - for detecting running processes

2. Detect from pyproject.toml

Read pyproject.toml to infer defaults:

# Project name
grep "^name" pyproject.toml

# Check for [project.scripts]
grep -A 5 "\[project.scripts\]" pyproject.toml

3. Generate launchd Directory

Create launchd/ directory:

mkdir -p launchd

4. Generate Files from Templates

For each template in skills/macos-launchd-service/templates/, perform substitutions:

Substitution variables:

{{DOMAIN}} - Reverse domain notation (e.g., "dev.pborenstein", "com.pborenstein")
{{PROJECT_NAME}} - Project name (e.g., "temoa")
{{MODULE_NAME}} - Python module name for import check
{{PORT}} - Port number
{{CLI_COMMAND}} - Full CLI command as plist array elements
{{DEV_COMMAND}} - Development mode command
{{PROCESS_NAME}} - Process name for pkill/pgrep
{{USERNAME}}, {{HOME}}, {{PROJECT_DIR}}, {{VENV_PYTHON}}, {{VENV_BIN}} - Auto-detected by install.sh

CLI_COMMAND special handling:

Must be converted to plist array format:

Input: "temoa server --host 0.0.0.0 --port 4001"

Output:
        <string>{{VENV_BIN}}/temoa</string>
        <string>server</string>
        <string>--host</string>
        <string>0.0.0.0</string>
        <string>--port</string>
        <string>4001</string>

5. Generated Files

install.sh (from install.sh.template):

Auto-detects environment (username, paths, venv)
Validates venv and module are installed
Generates service plist from template
Installs and loads service
Shows access information and management commands

uninstall.sh (from uninstall.sh.template):

Checks if service exists
Shows what will be removed
Asks for confirmation
Stops running service
Removes plist file
Confirms uninstall complete

{project}.plist.template (from service.plist.template):

Service configuration with substitution placeholders
Used by install.sh to generate final plist
Configured with RunAtLoad, KeepAlive for production

dev.sh (from dev.sh.template):

Stops launchd service if running
Runs app with auto-reload for development
Uses caffeinate to prevent sleep
Offers to restore service on exit

view-logs.sh (from view-logs.sh.template):

Modes: app logs, errors, or all
Uses tail -f for live viewing
Logs location: ~/Library/Logs/{project}.log

6. Make Scripts Executable

chmod +x launchd/install.sh
chmod +x launchd/uninstall.sh
chmod +x dev.sh
chmod +x view-logs.sh

7. Provide Next Steps

After generation, tell the user:

✓ Generated launchd service structure

Next steps:
1. Review generated files in launchd/
2. Run: ./launchd/install.sh
3. Access your service at: http://localhost:{PORT}
4. View logs: ./view-logs.sh
5. Development mode: ./dev.sh

Service will auto-start on login and auto-restart on crash.

Manage service:
  Stop:    launchctl unload ~/Library/LaunchAgents/{DOMAIN}.{project}.plist
  Start:   launchctl load ~/Library/LaunchAgents/{DOMAIN}.{project}.plist
  Status:  launchctl list | grep {project}

Example: temoa

Input parameters:

Domain: dev.pborenstein
Project name: temoa
Module name: temoa
Port: 4001
CLI command: temoa server --host 0.0.0.0 --port 4001 --log-level info
Dev command: temoa server --reload
Process name: temoa server

Generated CLI_COMMAND for plist:

    <array>
        <string>{{VENV_BIN}}/temoa</string>
        <string>server</string>
        <string>--host</string>
        <string>0.0.0.0</string>
        <string>--port</string>
        <string>4001</string>
        <string>--log-level</string>
        <string>info</string>
    </array>

Implementation Notes

Reading templates:

Templates are in skills/macos-launchd-service/templates/:

install.sh.template
uninstall.sh.template
service.plist.template
dev.sh.template
view-logs.sh.template

Writing generated files:

launchd/install.sh
launchd/uninstall.sh
launchd/{PROJECT_NAME}.plist.template
dev.sh
view-logs.sh

String substitution:

Simple replace all instances of each {{VARIABLE}} with its value.

CLI_COMMAND conversion:

Split on spaces, wrap each token in <string>TOKEN</string> with proper indentation.

Validation

After generation, verify:

All 5 files created (install.sh, uninstall.sh, plist.template, dev.sh, view-logs.sh)
Scripts are executable
No leftover {{VARIABLES}} in files
CLI_COMMAND properly formatted as plist array

Common Issues

Port conflicts: Use lsof -i :{PORT} to check if port is available

Module not found: User needs to run uv sync first

Permission errors: Ensure ~/Library/LaunchAgents exists

macos-launchd-service