Skip to content

sentinel

A lightweight process orchestrator CLI

Repository Information

Language Python
Stars 11
Forks 1
Last Updated 5/31/2026
View on GitHub

Sentinel

Python 3.14+ License: MIT Sponsor

A lightweight process orchestrator CLI


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
  • Persistent state across sessions

Installation

To run an interactive shell with Sentinel available without installing:

1nix shell github:4ster-light/sentinel -c bash

Or if you want to test a command directly:

1nix run github:4ster-light/sentinel -- <ARGS>

To install it into your Nix profile:

1nix profile add github:4ster-light/sentinel

If you want a specific release, pin the tag explicitly:

1nix <COMMAND> github:4ster-light/sentinel/<VERSION> # Only 0.2.0 onwards

If you are on NixOS add the flake to your system configuration.

Python (Uv)

If you prefer not to use Nix, you can still install Sentinel with uv:

1uv tool install git+https://github.com/4ster-light/sentinel@<VERSION> # if not specified it fetches latest

Alternatively using pip:

1pip install git+https://github.com/4ster-light/sentinel@<VERSION> # if not specified it fetches latest

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 port Manage port allocations
sentinel startup Generate startup scripts

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

Process Management

Starting a Process

Start a background process with sentinel run:

1# Basic usage2sentinel run "python server.py"34# Give the process a name for easier reference5sentinel run "python server.py" --name myserver67# Start multiple instances with derived names8sentinel run "python server.py" --name web --instances 3910# Enable auto-restart on crash or exit11sentinel run "npm start" --name frontend --restart1213# Add process to a group14sentinel run "python worker.py" --name worker1 --group workers1516# Use environment variables from a file17sentinel run "node app.js" --name app --env-file .env1819# Run as a specific system user (name or uid)20sentinel run "python worker.py" --name worker --user deploy2122# Add an HTTP health check (auto-restart still requires --restart)23sentinel run "python api.py" --name api --restart --health-http http://127.0.0.1:8000/health2425# Add a TCP health check with custom thresholds26sentinel run "python worker.py" --name worker --restart --health-tcp 127.0.0.1:9000 --health-interval 10 --health-failures 2

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

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

Startup Script Generation

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

1sentinel 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

Listing Processes

View all managed processes:

1sentinel list

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

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

Process Status

Get detailed information about a specific process:

1# By name2sentinel status myserver34# By ID5sentinel status 1

Output:

1myserver (id: 1)2  PID:       123453  Status:    running4  CPU:       2.1%5  Memory:    45.2MB6  Uptime:    5m 32s7  Restart:   no8  User:      default9  Group:     none10  CWD:       /home/user/project11  Command:   python server.py12  Stdout:    /home/user/.sentinel/logs/myserver.stdout.log13  Stderr:    /home/user/.sentinel/logs/myserver.stderr.log

Stopping Processes

Stop a running process:

1# By name2sentinel stop myserver34# By ID5sentinel stop 167# Force kill (SIGKILL instead of SIGTERM)8sentinel stop myserver --force

Restarting Processes

Restart a process (stops and starts it again):

1sentinel restart myserver

Viewing Logs

View stdout and stderr logs for a process:

1# Show last 50 lines (default)2sentinel logs myserver34# Show last 100 lines5sentinel logs myserver --lines 10067# Follow log output in real-time8sentinel logs myserver --follow910# Show only stdout11sentinel logs myserver --stream stdout1213# Show only stderr14sentinel logs myserver --stream stderr1516# Clear logs17sentinel 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:

1# Stop all processes2sentinel stopall34# Force stop all processes5sentinel stopall --force67# Start all stopped processes8sentinel startall910# Restart all processes11sentinel restartall

Cleaning Up

Remove dead processes from the state file:

1sentinel 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:

1# Start a process with restart flag2sentinel run "python worker.py" --name worker --restart34# If the process crashes, the next time you run list, it will be restarted5sentinel list6# 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:

1# Start the daemon2sentinel daemon start3# Output: Started daemon (pid: 54321)45# Check daemon status6sentinel daemon status7# Output: Daemon is running (pid: 54321)89# Stop the daemon10sentinel daemon stop11# 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.

Process Groups

Groups let you organize related processes together.

Creating Groups

1# Create a group2sentinel group create workers34# Create a group with environment variables5sentinel group create production --env "NODE_ENV=production" --env "PORT=3000"

Managing Group Membership

1# Add a process to a group (by process ID)2sentinel group add workers 134# Remove a process from a group5sentinel group remove workers 1

Listing Groups

1# List all groups2sentinel group list34# List processes in a specific group5sentinel group list workers

Group Operations

Control all processes in a group:

1# Start all processes in a group2sentinel group start workers34# Stop all processes in a group5sentinel group stop workers67# Restart all processes in a group8sentinel group restart workers

Deleting Groups

1# Delete a group (processes are unassigned but not stopped)2sentinel group delete workers34# Delete a group and stop all its processes5sentinel group delete workers --with-processes67# Alias for --with-processes8sentinel group delete workers --stop

Port Management

Sentinel can allocate and track ports for your processes.

Allocating Ports

1# Allocate a random available port2sentinel port allocate3# Output: Allocated port 8234 (default)45# Allocate a specific port6sentinel port allocate --port 800078# Allocate with a name9sentinel port allocate --name myapp10# Output: Allocated port 9123 (myapp)

Listing Ports

1sentinel port list

Output:

1+-------+---------+------------------+2|  PORT | NAME    | ALLOCATED        |3+-------+---------+------------------+4|  8000 | myapp   | 2024-01-15 10:30 |5|  8234 | default | 2024-01-15 10:35 |6+-------+---------+------------------+

Freeing Ports

1sentinel port free 8000

Configuration

Sentinel stores its state in ~/.sentinel/:

  • state.json - Process registry and port allocations
  • logs/ - Process stdout and stderr logs
  • daemon.pid - PID file for the restart daemon

Environment Variables

Process Environment

You can pass environment variables to processes:

1# Using an env file2sentinel 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:

1# Run by username2sentinel run "python worker.py" --name worker --user deploy34# Run by uid5sentinel 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:

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

Getting Help

View available commands:

1sentinel --help

Get help for a specific command:

1sentinel run --help2sentinel daemon --help3sentinel group --help4sentinel port --help

License

MIT

Want to see more? Visit my GitHub page for all my repositories and contributions.

View All Repositories on GitHub →