Kernel Mode

System Mode

System mode (--sys) runs one root-owned supervisor for the machine's services, with per-service privilege drops. It is the same sysg with the same commands — only the runtime it targets changes.

Runtimes

	User mode	System mode — Linux	System mode — macOS
State	`~/.local/share/systemg/`	`/var/lib/systemg/`	`/Library/Application Support/systemg/`
Logs	`~/.local/share/systemg/logs/`	`/var/log/systemg/`	`/Library/Logs/systemg/`
Config search	`~/.config/systemg/`	`/etc/systemg/`	`/Library/Application Support/systemg/etc/`
Boot integration	`systemd --user` unit, LaunchAgent	systemd unit	launchd daemon
Owner	invoking user	root	root

System mode uses each platform's native locations: the FHS on Linux, the /Library hierarchy on macOS where launchd — not systemd — owns system daemons.

--sys is always explicit. sysg never guesses the runtime from your EUID or from what exists on disk — it tells you when the modes cross:

SG0701 — running as root without --sys: warns that state will land in root's user-mode paths.
SG0702 — system-mode state exists but the command targets the user runtime: refuses rather than touch the wrong supervisor.
SG0704 — --sys without root: refused.

Running services as other users

version: "2"
services:
  db:
    command: "postgres -D /var/lib/postgresql/data"
    user: "postgres"
    group: "postgres"
  cache:
    command: "redis-server"
    user: "redis"

The identity drop is strictly ordered — rlimits, capability trimming, setgroups → setgid → setuid, ambient caps — with supplementary groups always reset before the UID switch and the environment cleared and rebuilt for the target account. Namespace unshare failures can warn and proceed (EPERM under nested containers), and cgroup attach happens post-spawn; see Sandboxing for what is and is not enforced.

Boot integration

sysg install-boot writes the unit that starts the system supervisor at boot — a systemd unit on a systemd-booted Linux host, a LaunchDaemon on macOS. A Linux box running some other init gets a refusal and the wrapper recipe instead:

$ sudo sysg --sys install-boot --config /etc/systemg/systemg.yaml --write --enable

[Service]
Type=simple
ExecStart=/usr/bin/sysg --sys start --attached --config /etc/systemg/systemg.yaml
KillMode=mixed
Restart=on-failure

Every sysg invocation in a unit carries --sys, and the unit runs start --attached so the process systemd tracks is the supervisor rather than a client that forked one. Every sysg self-exec (supervisor boot, live upgrade, recycle) forwards the mode across the exec boundary; the parity-supervisor-recycle lane guards this invariant.

Info

launchd bootstraps; sysg supervises. The generated plist restarts the supervisor only when it fails (KeepAlive: { SuccessfulExit: false }) — the launchd analogue of Restart=on-failure. sysg still owns every service's lifecycle, restarts, and health. Letting the manager also restart services would be double supervision with conflicting restart policies.

macOS system mode is boot integration plus native paths. The Linux-only kernel mechanisms — container-init, seccomp, Landlock, cgroups, namespaces — are refused with a diagnostic rather than silently ignored.

See Booting at Startup for user-scope units, running the supervisor as a non-root account, and what each setting in the generated unit is for.

Operator access

The control socket is owned by root with 0600 permissions and kernel peer credentials checked on every connection. In system mode this means all control — including status and logs — requires root (sudo). Finer-grained read-only access is not currently offered.

← How sysg Meets the Kernel Container-Init (PID 1) →