systemg

An agent-friendly general process composer.

Table of Contents

1. Read the Docs
2. Getting Started
   • 2.1 Installation
   • 2.2 Usage
3. Why systemg
   • 3.1 Features
4. How systemg Compares

Getting Started

Installation

$ curl --proto '=https' --tlsv1.2 -fsSL https://sh.sysg.dev/ | sh

For system-wide deployments, scripts/install-systemg.sh sets up /usr/bin/sysg, /etc/systemg, and /var/lib/systemg — see the security guide.

Usage

Describe your system in a systemg.yaml:

version: "2"
services:
  postgres:
    command: "postgres -D ./data"
    restart_policy: "always"

  api:
    command: "gunicorn app:application --bind 0.0.0.0:8000"
    depends_on:
      - postgres
    restart_policy: "on-failure"
    max_restarts: 5
    backoff: "5s"
    deployment:
      health_check:
        command: "curl --fail http://localhost:8000/health"

  backup:
    command: "sh backup.sh"
    cron:
      expression: "0 0 2 * * *"

Then run it:

sysg start --daemonize      # start everything, in dependency order
sysg status                 # see what's running
sysg logs --service api -f  # follow one service's logs
sysg restart --service api  # bounce one service, not the world

That's the whole workflow. Log rotation, output sinks, and status-snapshot tuning are covered in the configuration docs.

Run sysg start without --daemonize for a foreground attachment: systemg streams each service as service | line, updates slow boot progress in place, and stops only that project on Ctrl-C. The resident supervisor stays warm for other projects. Run sysg stop --supervisor when you intend to stop everything.

Why systemg

You declare your processes, their dependencies, and their health checks in one file. systemg starts them in topological order, restarts them according to policy, and won't call a rolling deploy done until the new process passes its health check.

It sits in the gap between systemd and Docker Compose. systemd wants to own the whole machine. Compose has the right composition model but makes you adopt containers to get it. Supervisor is close, but has no dependency graph and needs a Python runtime. systemg is one static binary that runs the same in a VM, a container, or on a Raspberry Pi — and everything it knows is readable back out through sysg status and sysg inspect, so scripts and coding agents can drive it as easily as you can.

Features

• Dependency-ordered startup, gated on health checks
• One resident supervisor for many isolated projects
• Rolling deployments: blue-green process swap, health-validated
• Restart policies with backoff
• Cron jobs with overlap detection
• Foreground multiplexed logs with per-service prefixes
• Same-PID live upgrades within a compatible release line
• Lifecycle hooks on start/stop
• .env file propagation
• Tracks child processes your services spawn
• CPU/RSS metrics built into status and inspect
• Privileged mode: per-service user/group, capabilities, rlimits, namespaces
• Uses systemd/cgroups when present; needs neither

How systemg Compares

	systemg	systemd	Supervisor	Docker Compose
Focus	Program composition	System management	Process supervision	Container orchestration
Config	YAML	Unit files	INI	YAML
Dependencies	Topological, health-aware	Unit chains	Manual ordering	Service links
Deployments	Built-in rolling	External tooling	Manual restarts	Recreate/rolling
Runtime deps	None	DBus, journal	Python	Docker daemon

Full documentation lives at sysg.dev. Maintainers and agents investigating supervisor behavior should begin with DEBUGGING.md.