sentinel

Sentinel

A universal process wrapper for monitoring and supervision. Works across containers (Docker/K8s), VMs, cron jobs, and systemd services.

Features

• Process Management: Signal forwarding, zombie reaping, exit code propagation
• PID 1 Mode: Proper init behavior when running as container entrypoint
• Restart Policies: never, always, on-failure with configurable retries and backoff
• Health Checks: Periodic health command execution
• Timeouts: Execution timeout, idle timeout (no output detection)
• Alerting: stderr, webhook (HTTP POST), custom scripts
• Structured Logging: Text or JSON format

Installation

go install github.com/4ba-Co/sentinel@latest

Or build from source:

go build -o sentinel .

Usage

sentinel [flags] -- command [args...]

Flags

Examples

One-shot job with timeout (cron):

sentinel --timeout 10m -- ./backup.sh

Long-running service with restart:

sentinel --restart on-failure --max-retries 5 -- ./my_server

Container entrypoint (PID 1):

ENTRYPOINT ["sentinel", "--grace-period=30s", "--"]
CMD ["/app/server"]

With health check and webhook alerts:

sentinel \
  --restart on-failure \
  --health-cmd "./healthcheck.sh" \
  --alert webhook \
  --webhook-url "https://hooks.slack.com/xxx" \
  -- ./my_server

Cron job with success and failure notifications:

sentinel \
  --alert-on-success \
  --alert script \
  --alert-cmd './notify.sh' \
  -- ./backup.sh

Cron job with only success notification (no start alert):

sentinel \
  --alert-events success \
  --alert script \
  --alert-cmd './notify.sh' \
  -- ./backup.sh

Using config file:

sentinel --config config.yaml -- ./my_app

Config File (YAML)

timeout: 30m
restart: on-failure
max_retries: 5
grace_period: 10s
health_cmd: "./healthcheck.sh"
health_interval: 30s
alert:
  - stderr
  - webhook
webhook_url: "https://hooks.slack.com/xxx"
alert_events:
  - exited
  - success
  - health_failed
log_format: json
success_codes:
  - 0
  - 143

Alert Script Environment

When using --alert-cmd, the script receives these environment variables:

• SENTINEL_EVENT: Event type (started, exited, success, timeout, restart, health_failed, killed)
• SENTINEL_EXIT_CODE: Process exit code
• SENTINEL_MESSAGE: Event description
• SENTINEL_COMMAND: The wrapped command
• SENTINEL_HOSTNAME: Host name

Note: By default, alerts are sent for all event types except success. Use --alert-on-success to add the success event, or --alert-events to specify exactly which events you want (e.g., --alert-events success,exited to receive only those two).

Alert Script Example

#!/bin/bash
case "$SENTINEL_EVENT" in
  success)
    curl -d "Backup completed on $SENTINEL_HOSTNAME" ntfy.sh/my-alerts
    ;;
  exited)
    curl -d "Backup FAILED (exit=$SENTINEL_EXIT_CODE): $SENTINEL_MESSAGE" ntfy.sh/my-alerts
    ;;
  health_failed)
    curl -d "Health check failed on $SENTINEL_HOSTNAME" ntfy.sh/my-alerts
    ;;
esac

Comparison

License

MIT