Skip to main content

Sentinel

A lightweight process orchestrator CLI

Release PyPI Platforms Nix flake COPR

CI COPR build Python 3.14+

Sponsor License: MIT


Features

  • Start and manage background processes with automatic logging
  • Real-time CPU, memory, and uptime monitoring
  • Automatic restart on process crash or exit
  • Process groups for organizing related processes
  • Size-based log rotation for stdout/stderr logs
  • Optional HTTP/TCP process health checks
  • Run processes as specific system users
  • Port allocation and management
  • Metrics export in JSON and table formats
  • Remote process management via SSH
  • Persistent state across sessions

Installation

Your situation Recommended What you get
Fedora 44, 45 or rawhide Fedora (COPR) Native package, updated by dnf, dependencies from the distribution
NixOS or Nix Nix Flake package and dev shell, no system Python needed
Linux or macOS with Python 3.14+ PyPI Isolated tool install, upgrades with uv tool upgrade sentinel-pm
Tracking main From git Latest unreleased changes from the repository

Fedora (COPR)

sudo dnf copr enable 4ster-light/sentinel-pm
sudo dnf install sentinel-pm

Nix

nix profile add github:4ster-light/sentinel

On NixOS add the flake to your system configuration.

PyPI

uv tool install sentinel-pm

With pip instead:

pip install sentinel-pm

From git

uv tool install git+https://github.com/4ster-light/sentinel

With pip instead:

pip install git+https://github.com/4ster-light/sentinel

Commands Overview

Command Description
sentinel run Start a background process
sentinel list List all managed processes
sentinel status Show detailed status of a process
sentinel stop Stop a running process
sentinel restart Restart a process
sentinel logs View process logs
sentinel clean Remove dead processes from state
sentinel stopall Stop all managed processes
sentinel startall Start all stopped processes
sentinel restartall Restart all managed processes
sentinel daemon Manage the restart monitor daemon
sentinel group Manage process groups
sentinel cluster Manage process clusters
sentinel port Manage port allocations
sentinel startup Generate startup scripts
sentinel metrics Export process metrics
sentinel remote Manage remote hosts via SSH

Run sentinel run --help to see process runtime options including --user, --startup-timeout, --instances, --scale, --depends-on, --nice, and --ionice.

Process Management

Starting a Process

Start a background process with sentinel run:

# Basic usage
sentinel run "python server.py"

# Give the process a name for easier reference
sentinel run "python server.py" --name myserver

# Start multiple instances with derived names
sentinel run "python server.py" --name web --instances 3

# Start a cluster that can grow later within a range
sentinel run "python server.py" --name web --scale 2-4

# Start only after another process is already running
sentinel run "python worker.py" --name worker --depends-on redis

# Enable auto-restart on crash or exit
sentinel run "npm start" --name frontend --restart

# Add process to a group
sentinel run "python worker.py" --name worker1 --group workers

# Use environment variables from a file
sentinel run "node app.js" --name app --env-file .env

# Run as a specific system user (name or uid)
sentinel run "python worker.py" --name worker --user deploy

# Add an HTTP health check (auto-restart still requires --restart)
sentinel run "python api.py" --name api --restart --health-http http://127.0.0.1:8000/health

# Add a TCP health check with custom thresholds
sentinel run "python worker.py" --name worker --restart --health-tcp 127.0.0.1:9000 --health-interval 10 --health-failures 2

--depends-on is repeatable and records the dependency on the process so group start, stopall, startall, and restartall order their work by it: dependencies start first and stop last. Starting a process whose dependency is unknown or not running is refused, and dependency cycles are reported before anything is started.

When you use --restart without the daemon running, you will see a warning:

Started myserver (id: 1, pid: 12345)
Warning: Restart flag set but daemon is not running. Restarts will only happen
when you run other sentinel commands.
  Run 'sentinel daemon start' for continuous monitoring.

Startup Script Generation

Generate a minimal systemd unit for a Sentinel-managed command:

sentinel startup systemd --name web --cwd /srv/web --restart python app.py

Output:

[Unit]
Description=Sentinel process: web
After=network.target

[Service]
Type=simple
WorkingDirectory=/srv/web
ExecStart=/usr/bin/env python app.py
Restart=always

[Install]
WantedBy=multi-user.target

SysV init.d Scripts

Generate an LSB-compatible init script for systems that boot with SysV init or OpenRC's sysv-rc compatibility layer:

sentinel startup initd --name web --cwd /srv/web --user deploy -- python app.py

The script writes its PID to /run/web.pid, appends output to /var/log/web.log, and supports start, stop, restart, and status:

sudo sentinel startup initd --name web python app.py > /etc/init.d/web
sudo chmod +x /etc/init.d/web
sudo update-rc.d web defaults   # Debian and Ubuntu
sudo chkconfig --add web        # RHEL and Fedora

Use --pidfile and --logfile to override the default paths. The command runs in its own session, so stop signals the whole process group and escalates to SIGKILL if the process does not exit within 30 seconds.

Windows Services

Generate a PowerShell script that installs the command as a Windows service through NSSM:

sentinel startup windows --name web --cwd C:\srv\web --restart python app.py | Out-File install-web.ps1

Run the generated script from an elevated PowerShell prompt:

.\install-web.ps1
.\install-web.ps1 -Uninstall   # remove the service again

The script registers sentinel-web with the automatic startup type and starts it. The first command token is the executable and the remaining tokens are its arguments. With --restart NSSM restarts the process when it exits; with --user the script prompts for the account password through Get-Credential instead of embedding a secret.

Listing Processes

View all managed processes:

sentinel list

Output shows a table with ID, name, PID, status, CPU usage, memory usage, uptime, restart flag, group, and command:

+----+----------+-------+---------+------+-------+--------+---------+---------+-------+-----------+
| ID | NAME     |   PID | STATUS  |  CPU |   MEM | UPTIME | RESTART | USER    | GROUP | COMMAND   |
+----+----------+-------+---------+------+-------+--------+---------+---------+-------+-----------+
|  1 | myserver | 12345 | running | 2.1% | 45 MB |   5m 3s|    -    |    -    |   -   | python ...|
|  2 | frontend | 12346 | running | 0.5% | 120MB |   2m 1s|    X    | deploy  |   -   | npm start |
+----+----------+-------+---------+------+-------+--------+---------+---------+-------+-----------+

Process Status

Get detailed information about a specific process:

# By name
sentinel status myserver

# By ID
sentinel status 1

Output:

myserver (id: 1)
  PID:       12345
  Status:    running
  CPU:       2.1%
  Memory:    45.2MB
  Uptime:    5m 32s
  Restart:   no
  User:      default
  Group:     none
  CWD:       /home/user/project
  Command:   python server.py
  Stdout:    /home/user/.sentinel/logs/myserver.stdout.log
  Stderr:    /home/user/.sentinel/logs/myserver.stderr.log

Stopping Processes

Stop a running process:

# By name
sentinel stop myserver

# By ID
sentinel stop 1

# Force kill (SIGKILL instead of SIGTERM)
sentinel stop myserver --force

Stopping signals the process's whole process group, so children of compound commands (npm run build && node server.js, background jobs) die with the leader.

Restarting Processes

Restart a process (stops and starts it again):

sentinel restart myserver

Viewing Logs

View stdout and stderr logs for a process:

# Show last 50 lines (default)
sentinel logs myserver

# Show last 100 lines
sentinel logs myserver --lines 100

# Follow log output in real-time
sentinel logs myserver --follow

# Show only stdout
sentinel logs myserver --stream stdout

# Show only stderr
sentinel logs myserver --stream stderr

# Clear logs
sentinel logs myserver --clear

Sentinel rotates process logs automatically when they exceed 10MB, keeping up to 3 backup files per stream (.1, .2, .3).

Bulk Operations

Control all processes at once:

# Stop all processes
sentinel stopall

# Force stop all processes
sentinel stopall --force

# Start all stopped processes
sentinel startall

# Restart all processes
sentinel restartall

Cleaning Up

Remove dead processes from the state file:

sentinel clean

This removes processes whose PIDs no longer exist from the state, without affecting running processes.

Auto-Restart

Sentinel can automatically restart processes that crash or exit. There are two ways this works:

Lazy Restart (Default)

When you run certain CLI commands (list, status), Sentinel checks for dead processes and restarts those with the restart flag enabled. This happens automatically without any extra setup.

Example:

# Start a process with restart flag
sentinel run "python worker.py" --name worker --restart

# If the process crashes, the next time you run list, it will be restarted
sentinel list
# Output: Auto-restarted worker (old_pid: 12345, new_pid: 12350)

Daemon Mode (Continuous Monitoring)

For continuous monitoring without needing to run CLI commands, start the daemon:

# Start the daemon
sentinel daemon start
# Output: Started daemon (pid: 54321)

# Check daemon status
sentinel daemon status
# Output: Daemon is running (pid: 54321)

# Stop the daemon
sentinel daemon stop
# Output: Stopped daemon (pid: 54321)

When the daemon is running, it checks every 5 seconds for crashed processes and restarts them automatically in the background. The daemon writes its activity to ~/.sentinel/daemon.log (rotated automatically).

Process Groups

Groups let you organize related processes together.

Creating Groups

# Create a group
sentinel group create workers

# Create a group with environment variables
sentinel group create production --env "NODE_ENV=production" --env "PORT=3000"

Managing Group Membership

# Add a process to a group (by process ID)
sentinel group add workers 1

# Remove a process from a group
sentinel group remove workers 1

Listing Groups

# List all groups
sentinel group list

# List processes in a specific group
sentinel group list workers

Group Operations

Control all processes in a group:

# Start all processes in a group
sentinel group start workers

# Stop all processes in a group
sentinel group stop workers

# Restart all processes in a group
sentinel group restart workers

Group operations honor --depends-on ordering: start and restart start dependencies first, while stop stops dependents first. A cycle or a missing dependency aborts the start with a message naming the processes involved.

# Inspect the recorded dependencies of a process
sentinel status worker

Deleting Groups

# Delete a group (processes are unassigned but not stopped)
sentinel group delete workers

# Delete a group and stop all its processes
sentinel group delete workers --with-processes

# Alias for --with-processes
sentinel group delete workers --stop

Process Clusters

--scale N starts N instances with a fixed size. --scale MIN-MAX starts MIN instances and records the range so the cluster can be resized later:

# Start two instances of web, growable up to four
sentinel run "python server.py" --name web --scale 2-4

# Show clusters, how many instances are running and their allowed range
sentinel cluster list

# Grow to four instances
sentinel cluster scale web 4

# Shrink back to two (the highest instance numbers are stopped)
sentinel cluster scale web 2

Scaling outside the recorded range is refused. Scaled-down instances are stopped and removed from state, and a restart keeps an instance in its cluster.

Port Management

Sentinel can allocate and track ports for your processes.

Allocating Ports

# Allocate a random available port
sentinel port allocate
# Output: Allocated port 8234 (default)

# Allocate a specific port
sentinel port allocate --port 8000

# Allocate with a name
sentinel port allocate --name myapp
# Output: Allocated port 9123 (myapp)

Listing Ports

sentinel port list

Output:

+-------+---------+------------------+
|  PORT | NAME    | ALLOCATED        |
+-------+---------+------------------+
|  8000 | myapp   | 2024-01-15 10:30 |
|  8234 | default | 2024-01-15 10:35 |
+-------+---------+------------------+

Freeing Ports

sentinel port free 8000

Metrics Export

Export process metrics in different formats for monitoring and automation.

Exporting Metrics

# Show metrics as a table (default)
sentinel metrics export

# Export as JSON
sentinel metrics export --format json

# Write metrics to a file
sentinel metrics export --output metrics.json

# Export JSON to a file
sentinel metrics export --format json --output metrics.json

Output (table format):

+----+----------+-------+---------+------+-------+--------+
| ID | NAME     |   PID | STATUS  |  CPU |   MEM | UPTIME |
+----+----------+-------+---------+------+-------+--------+
|  1 | myserver | 12345 | running | 2.1% | 45 MB |   5m 3s|
|  2 | frontend | 12346 | running | 0.5% | 120MB |   2m 1s|
+----+----------+-------+---------+------+-------+--------+

Output (JSON format):

[
  {
    "id": 1,
    "name": "myserver",
    "pid": 12345,
    "status": "running",
    "running": true,
    "cpu_percent": 2.1,
    "memory_mb": 45.2,
    "uptime_seconds": 303.0
  }
]

Prometheus

Export the metrics in the Prometheus text exposition format, or let Prometheus scrape them from a built-in HTTP endpoint:

# Write the exposition format to stdout
sentinel metrics export --format prometheus

# Write it to a file for the node exporter textfile collector
sentinel metrics export --format prometheus --output /var/lib/node_exporter/sentinel.prom

# Serve http://127.0.0.1:9464/metrics for Prometheus to scrape
sentinel metrics serve

Example output:

# HELP sentinel_processes_total Number of processes tracked by Sentinel.
# TYPE sentinel_processes_total gauge
sentinel_processes_total 2
# HELP sentinel_process_up Whether Sentinel sees the process as running (1) or not (0).
# TYPE sentinel_process_up gauge
sentinel_process_up{id="1",name="myserver"} 1
sentinel_process_up{id="2",name="frontend"} 0
# HELP sentinel_process_cpu_percent CPU usage of the process, in percent.
# TYPE sentinel_process_cpu_percent gauge
sentinel_process_cpu_percent{id="1",name="myserver"} 2.1

Add the scrape target to prometheus.yml:

scrape_configs:
  - job_name: sentinel
    static_configs:
      - targets: ["127.0.0.1:9464"]

The endpoint renders metrics on every scrape, so values are always current, and answers 404 for any path other than /metrics.

Quick Snapshot

Print a one-shot metrics table to stdout:

sentinel metrics snapshot

This is equivalent to sentinel metrics export without options.

Remote Management

Manage processes on remote hosts via SSH. Remote hosts must have Sentinel installed and accessible via SSH.

Registering Remote Hosts

# Add a remote host
sentinel remote add server1.example.com

# Add with SSH user
sentinel remote add server1.example.com --user deploy

# Add with custom SSH port
sentinel remote add server1.example.com --user deploy --port 2222

Listing Remote Hosts

# List all registered remote hosts
sentinel remote list

Output:

+---------------------+--------+------+------------------+
| HOST                | USER   | PORT | CREATED          |
+---------------------+--------+------+------------------+
| server1.example.com | deploy | 2222 | 2024-01-15 10:30 |
| server2.example.com | -      | -    | 2024-01-15 10:35 |
+---------------------+--------+------+------------------+

Running Commands on Remote Hosts

# List processes on a remote host
sentinel remote list server1.example.com

# Start a process on a remote host
sentinel remote run server1.example.com "python server.py"

# Stop a process on a remote host (use the ID shown by `remote list`)
sentinel remote stop server1.example.com 1

Removing Remote Hosts

sentinel remote remove server1.example.com

Configuration

Sentinel stores its state in ~/.sentinel/ by default (override the directory with the SENTINEL_STATE_DIR environment variable):

  • state.json - Process registry, port allocations, and remote hosts. Written atomically and guarded against corruption.
  • state.json.lock - Advisory lock coordinating concurrent Sentinel writers (the daemon and CLI commands).
  • logs/ - Process stdout and stderr logs
  • daemon.pid - PID file for the restart daemon
  • daemon.log - Rotating log of daemon activity (restarts, errors)

If state.json is ever unreadable, Sentinel backs it up to state.json.corrupt-<timestamp>, prints a warning, and starts from an empty state instead of silently discarding your data.

Environment Variables

Process Environment

You can pass environment variables to processes:

# Using an env file
sentinel run "node app.js" --env-file .env

Sentinel also looks for environment files in:

  • ~/.sentinel/.env (global)
  • ./.env (current directory)

Process User

Run commands as a specific local system user:

# Run by username
sentinel run "python worker.py" --name worker --user deploy

# Run by uid
sentinel run "python worker.py" --name worker --user 1001

Notes:

  • Switching to another user generally requires root privileges.
  • If you run Sentinel without root, use your current user.

Group Environment

Groups can have environment variables that are passed to all processes in the group:

sentinel group create staging --env "DATABASE_URL=postgres://..." --env "DEBUG=true"

Getting Help

View available commands:

sentinel --help

Get help for a specific command:

sentinel run --help
sentinel daemon --help
sentinel group --help
sentinel port --help
sentinel metrics --help
sentinel remote --help

License

MIT

Metadata

Release files for sentinel-pm 0.2.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sentinel-pm 0.2.6
File Size Uploaded Provenance Actions
sentinel_pm-0.2.6.tar.gz 45.1 kB With provenance Details for sentinel_pm-0.2.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sentinel-pm 0.2.6
File Interpreter ABI Platform Actions
sentinel_pm-0.2.6-py3-none-any.whl Python 3 none any Details for sentinel_pm-0.2.6-py3-none-any.whl

Total release size: 102.2 kB

Release files / sentinel_pm-0.2.6.tar.gz

Download URL sentinel_pm-0.2.6.tar.gz
Size 45.1 kB
Tags Source
SHA-256 checksum
How to use checksums
46b18bad908e0ebe7c81767e957411eba07160e30aa5d5d805e1220b0f4df3f1
BLAKE2b-256 checksum
How to use checksums
80b0258f8a2a518dd24aa0589091654c5c5f8b5f0b2184049e89cd1aa748b6cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / sentinel_pm-0.2.6-py3-none-any.whl

Download URL sentinel_pm-0.2.6-py3-none-any.whl
Size 57.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0a2f6b22c81ad576591388ecee544a35b524f45414e94dd84d3c84650aa3c262
BLAKE2b-256 checksum
How to use checksums
c3c62151c6cd7e7eaec7524d9bba9a02f628548a9578a61302bb4e30d6f153b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for sentinel-pm 0.2.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sentinel_pm-0.2.6.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.6 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page