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

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"
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, timeout, restart, health_failed, killed)
• SENTINEL_EXIT_CODE: Process exit code
• SENTINEL_MESSAGE: Event description
• SENTINEL_COMMAND: The wrapped command
• SENTINEL_HOSTNAME: Host name

Comparison

License

MIT