py-simple-service-manager

py-simple-service-manager lets you manage a one-line command as a service on Linux, Windows, and macOS.

The same Python runner handles command execution, retry attempts, status files, and stdout/stderr logs. Platform backends only register and control the runner:

• Linux: systemd units controlled by systemctl
• Windows: Task Scheduler tasks controlled by schtasks and PowerShell
• macOS: launchd agents/daemons controlled by launchctl

Install

python -m pip install -e .

Administrator relaunch support uses py-admin-launch for Windows UAC, Linux pkexec/sudo, and macOS osascript/sudo.

Startup modes

• manual: do not start at boot.
• auto: start once at boot after network components are available.
• auto-retry: start at boot and retry after K seconds up to N times when the command exits with a non-zero code.

The retry count is handled by this package's runner, so it works consistently across all supported platforms.

pssm logs and the GUI log tabs read the current log files, not only completed runs. The runner flushes stdout/stderr to disk as bytes arrive, and Python commands are launched with unbuffered output automatically.

Usage

Register a manual service:

pssm add api -- python -m http.server 9000

Register a boot service:

pssm add api --mode auto -- python -m http.server 9000

Register a boot service with retry:

pssm add worker --mode auto-retry --retry-delay 10 --retry-limit 5 -- python worker.py

Set a per-run timeout, or use None for no time limit:

pssm add api --timeout 30 -- python -m http.server 9000
pssm edit api --timeout None

Change startup mode later:

pssm mode worker manual
pssm mode worker auto-retry --retry-delay 10 --retry-limit 5

Inspect and control services:

pssm list
pssm status worker
pssm logs worker
pssm logs worker --stream stderr --lines 100
pssm start worker
pssm stop worker
pssm remove worker

Edit the same fields exposed by the GUI:

pssm edit worker --command "python worker.py --queue default" --cwd /path/to/app
pssm edit worker --mode auto-retry --retry-delay 10 --retry-limit 5 --timeout 60
pssm edit worker --clear-cwd

Open the GUI:

pssm gui
pssm-gui

The GUI supports listing services, creating services, editing command/startup mode/retry settings/timeout/working directory, deleting services, starting and force-stopping services, viewing stdout/stderr, and viewing start history. The selected service status shows whether the current run is still active and how many seconds it has been running. Anything the GUI can change is also available through the CLI.

Show storage paths and platform details:

pssm doctor

Services are managed in system scope. Commands relaunch with administrator/root privileges automatically when needed.

Platform notes

Linux

Linux requires systemd and systemctl.

• System scope writes units to /etc/systemd/system.
• Boot startup uses network-online.target with Wants= and After=.

Windows

Windows uses Task Scheduler.

• Services are registered as system tasks:

pssm add name --mode auto -- your-command

System-scope tasks run as SYSTEM with highest available privileges. Make sure the command and Python environment are available to that account.

macOS

macOS uses launchd.

• System scope writes LaunchDaemons to /Library/LaunchDaemons.
• Boot startup maps to RunAtLoad=true.

Development

Run tests from source:

PYTHONPATH=src python -m unittest discover -s tests -v

On Windows PowerShell:

$env:PYTHONPATH = "src"
python -m unittest discover -s tests -v