systemg 0.67.2

An agent-friendly general-purpose program orchestrator for busy people.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176

# systemg

An agent-friendly general-purpose program orchestrator for busy people.

<br/><br/>

<div align="center" >
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ra0x3/systemg/main/sysg.dev/public/img/full-logo-colored-cropped-darkmode.png" />
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ra0x3/systemg/main/sysg.dev/public/img/full-logo-colored-cropped.png" />
    <img src="https://raw.githubusercontent.com/ra0x3/systemg/main/sysg.dev/public/img/full-logo-colored-cropped.png" alt="systemg" width="320" />
  </picture>
</div>

<br/><br/>

<div align="center">

[![Live](https://img.shields.io/badge/live-sysg.dev-E0111D?style=flat-square&logo=safari&logoColor=white)](https://sysg.dev)
[![CI](https://img.shields.io/github/actions/workflow/status/ra0x3/systemg/ci.yaml?branch=main&style=flat-square&logo=github&label=CI)](https://github.com/ra0x3/systemg/actions/workflows/ci.yaml)
[![GitHub branch status](https://img.shields.io/github/checks-status/ra0x3/systemg/main?style=flat-square&label=checks)](https://github.com/ra0x3/systemg/actions)

[![docs.rs (with version)](https://img.shields.io/docsrs/systemg/latest)](https://docs.rs/systemg)
[![GitHub tag](https://img.shields.io/github/v/tag/ra0x3/systemg?style=flat-square&logo=github&label=version)](https://github.com/ra0x3/systemg/releases)
[![Crate size](https://img.shields.io/crates/size/systemg?style=flat-square&logo=rust&label=size)](https://crates.io/crates/systemg)
![Crates.io Total Downloads](https://img.shields.io/crates/d/systemg)

[![Deps.rs Crate Dependencies (specific version)](https://img.shields.io/deps-rs/systemg/latest)](https://deps.rs/crate/systemg)
[![License](https://img.shields.io/crates/l/systemg?style=flat-square)](LICENSE)

</div>

<div align="center">
    <img src="https://img.shields.io/badge/Rust-000000?style=for-the-badge&logo=rust&logoColor=white" />
    <img src="https://img.shields.io/badge/ts--node-3178C6?style=for-the-badge&logo=ts-node&logoColor=white" />
    <img src="https://img.shields.io/badge/Vite-B73BFE?style=for-the-badge&logo=vite&logoColor=FFD62E" />
    <img src="https://img.shields.io/badge/mac%20os-000000?style=for-the-badge&logo=apple&logoColor=white" />
    <img src="https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" />
    <img src="https://img.shields.io/badge/OpenAI-412991?style=for-the-badge&logo=openai&logoColor=white" />
    <img src="https://img.shields.io/badge/Anthropic-D97757?style=for-the-badge&logo=anthropic&logoColor=white" />
</div>

[//]: # (<img height="500px" src="https://i.imgur.com/MHXfe9T.png" />)

## Table of Contents

1. [Read the Docs](https://sysg.dev)
2. [Getting Started](#getting-started)
   - 2.1 [Installation](#installation)
   - 2.2 [Usage](#usage)
3. [Why systemg](#why-systemg)
   - 3.1 [Features](#features)
4. [How systemg Compares](#how-systemg-compares)

## Getting Started

### Installation

![Installation](https://i.imgur.com/JHQPtJp.gif)

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

Or with Homebrew, on macOS and Linux:

```sh
$ brew install ra0x3/tap/sysg
```

For system-wide deployments, `scripts/install-systemg.sh` sets up `/usr/bin/sysg`, `/etc/systemg`, and `/var/lib/systemg` — see the [security guide](docs/security.mdx).

Nothing supervises the supervisor, so a reboot leaves the machine bare until a service manager starts one. `sysg install-boot` writes that unit — a systemd unit or a launchd daemon, for the machine or for your own account:

```console
$ sysg install-boot --config /opts/app/sysg.prod.yaml --write --enable
```

### Usage

Describe your system in a `systemg.yaml`:

```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:

```sh
sysg start --daemonize      # start everything, in dependency order
sysg status                 # see what's running
sysg logs --service api --lines 0 --follow  # stream only new service 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](docs/how-it-works/configuration.mdx).

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
- Process [hooks](docs/how-it-works/hooks.mdx) on successful starts and unsuccessful exits
- `.env` file propagation
- Tracks child processes your services spawn
- CPU/RSS metrics built into `status` and `inspect`
- [Privileged mode](docs/how-it-works/privileged-mode.mdx): 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** | No interpreter or VM; `command:` uses a POSIX shell | DBus, journal | Python | Docker daemon |

### Measured

| | systemg | systemd | Supervisor | Docker Compose |
|---------|---------|---------|------------|----------------|
| Install to first service | 1.49s | — | 5.53s | 15.85s+ (package only) |
| Pulled over network | 6.8 MB | — | 48.0 MB | 172.5 MB |
| Installed on disk | 19.5 MB | 14.6 MB | 26.8 MB | 278.6 MB |
| Ten-service graph | 6.91s | — | n/a | 8.31s |
| Overhead at ten services | 12.4 MB | — | 18.1 MB | ~354 MB |
| Added per service | 0.035 MB | — | 0.020 MB | 7.26 MB |
| Expresses a dependency graph | ✓ | ✓ | ✗ | ✓ |
| Gates on a probe, not a timer | ✓ | ✓ | ✗ | ✓ |
| Leaves nothing behind on stop | ✓ | — | ✗ | ✓ |
| Workload survives its crash | ✓ | — | ✓ | ✗ |
| Starts no duplicate after | ✓ | — | ✗ | ✓ |
| Recovers without an operator | ✓ | — | ✓ | ✗ |
| Runs without a separate runtime | ✓ | ✓ | ✗ | ✗ |
| Installs without root | ✓ | ✗ | ✓ | ✗ |

Full documentation lives at [sysg.dev](https://sysg.dev). Maintainers and
agents investigating supervisor behavior should begin with
[DEBUGGING.md](DEBUGGING.md).