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 logsdaemon.pid- PID file for the restart daemondaemon.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.