{"id":50851766,"url":"https://github.com/rodmena-limited/supervice","last_synced_at":"2026-06-14T14:03:17.934Z","repository":{"id":336993325,"uuid":"1148430444","full_name":"rodmena-limited/supervice","owner":"rodmena-limited","description":"process supervisor for Unix-like systems - zero dependencies","archived":false,"fork":false,"pushed_at":"2026-02-07T06:19:01.000Z","size":101,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-07T16:34:02.519Z","etag":null,"topics":["process-manager","supervisorctl","supervisord"],"latest_commit_sha":null,"homepage":"https://supervice.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rodmena-limited.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-03T00:36:48.000Z","updated_at":"2026-02-07T06:21:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rodmena-limited/supervice","commit_stats":null,"previous_names":["rodmena-limited/supervice"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rodmena-limited/supervice","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodmena-limited%2Fsupervice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodmena-limited%2Fsupervice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodmena-limited%2Fsupervice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodmena-limited%2Fsupervice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rodmena-limited","download_url":"https://codeload.github.com/rodmena-limited/supervice/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodmena-limited%2Fsupervice/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34324004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["process-manager","supervisorctl","supervisord"],"created_at":"2026-06-14T14:03:17.119Z","updated_at":"2026-06-14T14:03:17.929Z","avatar_url":"https://github.com/rodmena-limited.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Supervice\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy--strict-blue.svg)](https://mypy-lang.org/)\n[![Documentation](https://readthedocs.org/projects/supervice/badge/?version=latest)](https://supervice.readthedocs.io)\n\nA modern, lightweight, and fully async process supervisor for Unix-like systems.\n**Zero dependencies. Pure Python. Production-ready.**\n\nSupervice manages long-running processes with automatic restart, health checking,\nprocess grouping, hot config reload, and a Unix socket RPC interface — all built\non Python's `asyncio` with no external packages.\n\n---\n\n## Features\n\n- **Async-first** — Built entirely on `asyncio` for efficient I/O multiplexing\n- **Zero dependencies** — Pure Python stdlib; nothing to install beyond Python 3.10+\n- **Process groups** — Organize related processes and control them as a unit\n- **Health checks** — TCP connectivity and script-based health monitoring with auto-restart\n- **Hot reload** — Add/remove programs without restarting the daemon (`supervicectl reload`)\n- **Daemon mode** — Proper double-fork daemonization with PID file locking\n- **Graceful shutdown** — SIGTERM/SIGINT triggers orderly stop of all child processes\n- **Process group kill** — Stops entire process trees, not just the main PID\n- **Log rotation** — Built-in `RotatingFileHandler` with configurable size and backup count\n- **Uptime tracking** — Per-process wall-clock uptime displayed in status output\n- **Retry with backoff** — Configurable start retries with automatic FATAL state on exhaustion\n- **User switching** — Run processes as a specific user (requires root)\n- **Type-safe** — Fully type-hinted, passes `mypy --strict`\n\n## Installation\n\n**Requirements:** Python 3.10+ on a Unix-like OS (Linux, macOS).\n\n```bash\n# From source\ngit clone https://github.com/yourusername/supervice.git\ncd supervice\npip install .\n\n# Development install (includes docs dependencies)\npip install -e \".[docs]\"\n```\n\n## Quick Start\n\n### 1. Create a configuration file\n\n```ini\n# supervisord.conf\n[supervice]\nloglevel = INFO\nlogfile = supervice.log\npidfile = supervice.pid\n\n[program:webapp]\ncommand = python3 -u app.py\nautostart = true\nautorestart = true\nstdout_logfile = webapp.log\nstderr_logfile = webapp_err.log\n\n[program:worker]\ncommand = python3 -u worker.py\nnumprocs = 4\nautostart = true\nautorestart = true\nstdout_logfile = worker_%(process_num)s.log\nstderr_logfile = worker_err_%(process_num)s.log\n```\n\n### 2. Start the daemon\n\n```bash\n# Foreground (development)\nsupervice -c supervisord.conf -n\n\n# Background (production — default)\nsupervice -c supervisord.conf\n```\n\n### 3. Control processes\n\n```bash\n# Check status\nsupervicectl status\n\n# Output:\n# NAME                 STATE      PID        UPTIME\n# --------------------------------------------------------\n# webapp               RUNNING    12345      1:23:45\n# worker:00            RUNNING    12346      1:23:44\n# worker:01            RUNNING    12347      1:23:44\n# worker:02            RUNNING    12348      1:23:44\n# worker:03            RUNNING    12349      1:23:44\n\n# Start / stop / restart individual processes\nsupervicectl stop worker:00\nsupervicectl start worker:00\nsupervicectl restart worker:00\nsupervicectl restart worker:00 --force   # SIGKILL instead of graceful\n\n# Group operations\nsupervicectl stopgroup workers\nsupervicectl startgroup workers\n\n# Hot reload (add/remove programs without restart)\nsupervicectl reload\n\n# Use a custom socket path\nsupervicectl -s /var/run/supervice.sock status\n```\n\n## Configuration Reference\n\n### `[supervice]` — Global settings\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `logfile` | `supervice.log` | Path to the daemon log file |\n| `loglevel` | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |\n| `pidfile` | `supervice.pid` | Path to the PID/lock file |\n| `socket` | `/tmp/supervice.sock` | Unix socket path for RPC |\n| `shutdown_timeout` | `30` | Seconds to wait for graceful shutdown |\n| `log_maxbytes` | `52428800` | Max log file size before rotation (bytes, 0 = no rotation) |\n| `log_backups` | `10` | Number of rotated log backup files to keep |\n\n### `[program:NAME]` — Process definitions\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `command` | *(required)* | Command to execute (supports shell-style quoting) |\n| `numprocs` | `1` | Number of instances to run (creates `NAME:00`, `NAME:01`, ...) |\n| `autostart` | `true` | Start automatically when daemon starts |\n| `autorestart` | `true` | Restart automatically when process exits |\n| `startsecs` | `1` | Seconds a process must run to be considered successfully started |\n| `startretries` | `3` | Max consecutive start attempts before entering FATAL state |\n| `stopsignal` | `TERM` | Signal to send when stopping (`TERM`, `INT`, `QUIT`, `KILL`, etc.) |\n| `stopwaitsecs` | `10` | Seconds to wait after stop signal before sending SIGKILL |\n| `stdout_logfile` | *(none)* | File for stdout (supports `%(process_num)s` substitution) |\n| `stderr_logfile` | *(none)* | File for stderr (supports `%(process_num)s` substitution) |\n| `environment` | *(none)* | Environment variables: `KEY=VAL,KEY2=\"val with,comma\"` |\n| `directory` | *(none)* | Working directory for the process |\n| `user` | *(none)* | Run as this user (requires root privileges) |\n\n### `[group:NAME]` — Process groups\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `programs` | *(required)* | Comma-separated list of program names |\n\n### Health check options (per program)\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `healthcheck_type` | `none` | Health check type: `none`, `tcp`, `script` |\n| `healthcheck_interval` | `30` | Seconds between health checks |\n| `healthcheck_timeout` | `10` | Seconds to wait for health check response |\n| `healthcheck_retries` | `3` | Consecutive failures before marking unhealthy |\n| `healthcheck_start_period` | `10` | Seconds to wait before starting health checks |\n| `healthcheck_port` | *(none)* | TCP port to check (required for `tcp` type) |\n| `healthcheck_host` | `127.0.0.1` | TCP host to check |\n| `healthcheck_command` | *(none)* | Script to run (required for `script` type) |\n\n**Example with health checks:**\n\n```ini\n[program:api]\ncommand = python3 -u api_server.py\nautostart = true\nautorestart = true\nhealthcheck_type = tcp\nhealthcheck_port = 8080\nhealthcheck_interval = 15\nhealthcheck_retries = 3\nhealthcheck_start_period = 5\n```\n\n## Process States\n\n```\nSTOPPED ──┐\nEXITED  ──┼──\u003e STARTING ──\u003e RUNNING ──\u003e STOPPING ──\u003e STOPPED\nFATAL   ──┤                    │                        │\nBACKOFF ──┘                    │                     EXITED\n                               ▼\n                           UNHEALTHY (health check failures)\n                               │\n                               ▼\n                         auto-restart (if autorestart=true)\n```\n\n| State | Description |\n|-------|-------------|\n| `STOPPED` | Process is not running (initial or manually stopped) |\n| `STARTING` | Process has been spawned, waiting for confirmation |\n| `RUNNING` | Process is running and healthy |\n| `BACKOFF` | Process exited too quickly, waiting before retry |\n| `STOPPING` | Stop signal sent, waiting for process to exit |\n| `EXITED` | Process has exited (normally or abnormally) |\n| `FATAL` | Process failed to start after exhausting retries |\n| `UNHEALTHY` | Process is running but health checks are failing |\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────┐\n│                   supervice                      │\n│                                                  │\n│  ┌──────────┐    ┌───────────┐    ┌──────────┐  │\n│  │  Config   │───▶│ Supervisor │───▶│ Process  │  │\n│  │  Parser   │    │   (core)   │    │ Manager  │  │\n│  └──────────┘    └─────┬─────┘    └────┬─────┘  │\n│                        │               │         │\n│                   ┌────▼────┐    ┌─────▼─────┐  │\n│                   │   RPC    │    │  EventBus  │  │\n│                   │  Server  │    │  (pub/sub) │  │\n│                   └────┬────┘    └───────────┘  │\n│                        │                         │\n└────────────────────────┼─────────────────────────┘\n                         │ Unix Socket\n                    ┌────▼────┐\n                    │supervice│\n                    │  ctl    │\n                    └─────────┘\n```\n\n## Documentation\n\nFull documentation is available at [supervice.readthedocs.io](https://supervice.readthedocs.io).\n\n## Development\n\n```bash\n# Run tests\npython3 -m pytest tests/ -v\n\n# Type checking (strict mode)\nmypy --strict supervice/\n\n# Linting\nruff check supervice/\n\n# Formatting\nruff format supervice/\n\n# Build documentation locally\npip install -e \".[docs]\"\ncd docs \u0026\u0026 make html\n```\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE) for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodmena-limited%2Fsupervice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frodmena-limited%2Fsupervice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodmena-limited%2Fsupervice/lists"}