Language	Python
Stars	10
Forks	1
Last Updated	4/12/2026

Sentinel

A lightweight process supervisor CLI for managing background processes.

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

Using uv (recommended):

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

Using pip:

1pip 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 port`	Manage port allocations

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

Process Management

Starting a Process

Start a background process with sentinel run:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23# Basic usage
sentinel run "python server.py"

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

# 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

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

1
2
3
4Started 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.

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
3
4
5
6+----+----------+-------+---------+------+-------+--------+---------+---------+-------+-----------+
| 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:

1
2
3
4
5# By name
sentinel status myserver

# By ID
sentinel status 1

Output:

1
2
3
4
5
6
7
8
9
10
11
12
13myserver (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:

1
2
3
4
5
6
7
8# By name
sentinel stop myserver

# By ID
sentinel stop 1

# Force kill (SIGKILL instead of SIGTERM)
sentinel 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17# 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:

1
2
3
4
5
6
7
8
9
10
11# 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:

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
2
3
4
5
6# 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:

1
2
3
4
5
6
7
8
9
10
11# 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.

Process Groups

Groups let you organize related processes together.

Creating Groups

1
2
3
4
5# 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

1
2
3
4
5# 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

1
2
3
4
5# List all groups
sentinel group list

# List processes in a specific group
sentinel group list workers

Group Operations

Control all processes in a group:

1
2
3
4
5
6
7
8# 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

Deleting Groups

1
2
3
4
5
6
7
8# 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

Port Management

Sentinel can allocate and track ports for your processes.

Allocating Ports

1
2
3
4
5
6
7
8
9
10# 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

1sentinel port list

Output:

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

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
2# 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:

1
2
3
4
5# 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:

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

Getting Help

View available commands:

1sentinel --help

Get help for a specific command:

1
2
3
4sentinel run --help
sentinel daemon --help
sentinel group --help
sentinel port --help

License

MIT

Repository Information