py-simple-service-manager 0.1.0

Cross-platform command-as-service manager for Windows, Linux systemd, and macOS launchd.

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 .

Optional administrator relaunch support:

python -m pip install -e ".[admin]"

The admin extra 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 --scope system --elevate add api --mode auto -- python -m http.server 9000

Register a boot service with retry:

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

Change startup mode later:

pssm mode worker manual
pssm --scope system --elevate 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 --force
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
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/working directory, deleting services, starting and stopping services, and viewing stdout/stderr. Anything the GUI can change is also available through the CLI.

Show storage paths and platform details:

pssm doctor

--scope can be user, system, or auto. auto uses system when the current process is already elevated, otherwise user.

Platform notes

Linux

Linux requires systemd and systemctl.

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

For user units that should survive logout, enable lingering outside this tool:

loginctl enable-linger "$USER"

Windows

Windows uses Task Scheduler.

• Manual services can be registered in user scope.
• Boot startup requires system scope and elevation:

pssm --scope system --elevate 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.

• User scope writes LaunchAgents to ~/Library/LaunchAgents.
• 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