_{▶ 30-second trailer — watch in full resolution, with sound}

A minimal PID 1 init system for Linux that supervises services through a weight-state machine instead of unit files and dependency graphs.

No systemd. No OpenRC. No journal daemon. No socket activation engine. Just a statically linked binary that mounts your filesystems, spawns your services in dependency order, and watches them — then gets out of the way.

PID 1 footprint: 1.2 MB RSS on a minimal boot, 3.3–4.0 MB running a 47-service KDE desktop — one thread, in every case. Every footprint figure in this README names the machine, the build and the service count it was measured on: see PID 1 RSS — every measurement.

systemd isn't just PID 1 — it's a constellation of always-on daemons: journald, systemd-logind, dbus-broker, systemd-resolved, resident udevd workers, timers firing on their own schedule. Each one holds RAM and wakes the CPU whether or not you're using it. schema-init replaces PID 1 with a single static binary and does none of that — no journal database, no socket-activation engine, no background event loops. What that machinery was holding comes back to you.

Your RAM comes back. On identical hardware running the identical desktop, schema-init frees roughly half a gigabyte of RAM that systemd's daemon stack was sitting on (~1.1 GB used at desktop vs ~1.6–2.0 GB — see Real numbers), and idle swap drops from hundreds of MB to zero. In lived terms that is the difference between a few browser tabs plus one other program before the machine starts thrashing and two or three browsers with ~20 tabs each and a game running at the same time — same RAM, no upgrade. The computer you already own effectively gets bigger.

Your power comes back. With no ambient timer wakeups holding the cores awake, the CPU actually reaches its deepest hardware sleep state: measured 92–99% C10 residency and ~1.25 W full-SoC package draw at a working desktop, idle load average 0.03 (vs 0.10–0.20 under systemd). Those figures are read from Intel RAPL hardware energy counters, not estimated. Per machine it is a small, honest number — but it is structural, paid back every second of every idle hour. schema-init's part is simply removing the constant wakeups that keep silicon out of deep sleep in the first place.

On extrapolating this: don't. These are single-node measurements on one i3 laptop. An init system's own power draw is a tiny slice of a server's total, so multiplying a per-node idle delta by a fleet size produces a number that will not survive contact with anyone who runs real hardware. If schema-init saves money at scale, the levers are density, footprint, boot time, attack surface and determinism — not init power draw.

The machine goes quiet, not just lean. One PID-1 thread instead of 20–30. A tick loop that sleeps indefinitely once services are stable — nothing wakes it on a schedule. No journal flush, no D-Bus polling, no watchdog chatter. The hardware is allowed to actually rest.

This isn't theory or a benchmark rig — it's a salvaged Dell Inspiron (Intel i3, 4 GB) that swapped constantly under systemd and now runs a full desktop with room to spare under schema-init. Older and low-RAM machines benefit the most: the daemons you delete are the exact ones a small machine can least afford.

PID 1 footprint: 1.2 MB RSS on a minimal boot, 3.3–4.0 MB running a 47-service KDE desktop — one thread, in every case. Every footprint figure in this README names the machine, the build and the service count it was measured on: see PID 1 RSS — every measurement.

Every service moves through a state machine driven by probes. Before a service is spawned, schema-init probes the system — is the binary present? Are dependencies stable? Is there enough memory? The probe returns a flag word. The state machine decides what comes next.

                  ┌─────────────────────────────────────┐
                  │                                     │
            NEW_PROCESS                                 │
                  │                                     │
           F8 probe passes                              │
                  │                                     │
            FULL_TRUST ──── stable 10s ──── FUNDAMENTAL │
                  │                         SETTLED     │
                  │                                     │
             (oneshot exit 0)                           │
                  │                                     │
              PERFECT                                   │
                                                        │
            ── on death ──                              │
                  │                                     │
             RECOVERY ◄──────────────────────────────── ┘
                  │
           F9 probe fails
                  │
             FRICTION
                  │
           F6 probe fails
                  │
             DORMANT  (75 — backoff anteroom: 5m → 10m → 20m → 40m → 60m)
                  │
         (non-critical, 5 cycles exhausted)
                  │
             EXCISED  (76 — gate closes)

Three probe families:

Services marked critical=1 never reach EXCISED — they enter DORMANT and retry at 1-hour intervals indefinitely. Non-critical services excise after 5 dormant cycles (~75 minutes). A dep marked critical=1 that is EXCISED still blocks its dependents. A non-critical EXCISED dep is skipped — dependents proceed without it.

If you're reading the source to evaluate it, start here. The whole init is ~2,500 lines of C with no external dependencies.

Read these first, in this order:

Supporting binaries:

Directories:

Top-level: setup.sh (newcomer bootstrap — dep check, desktop-environment detection, GRUB entry generation) and Makefile (static build; see Building).

Drop a .svc file in /etc/schema-init/services/. One key=value per line:

name=sshd
exec=/usr/sbin/sshd
args=-D
needs_root=1

name=display-manager
exec=/usr/sbin/lightdm
dep=dbus
dep=udev
needs_root=1
critical=1

name=network
exec=/usr/local/bin/net-setup
oneshot=1

Keys:

A full example using readiness probes:

name=dbus
exec=/usr/bin/dbus-daemon
args=--system
args=--nofork
needs_root=1
stable_secs=2
ready_path=/run/dbus/system_bus_socket

For fleets of identical services — e.g. 49 joint controllers on an exoskeleton — define config once and symlink instances:

# template — write once
/etc/schema-init/services/motor@.svc

# instances — zero-byte symlinks; suffix becomes $INSTANCE in the child
ln -s motor@.svc /etc/schema-init/services/motor@0.svc
ln -s motor@.svc /etc/schema-init/services/motor@12.svc
ln -s motor@.svc /etc/schema-init/services/motor@48.svc

At boot, motor@.svc is skipped as a non-spawnable template. Each motor@N.svc symlink loads config from the template and spawns the binary with INSTANCE=N in the child environment. The motor controller reads $INSTANCE to determine its joint index, SPI bus address, or any other per-instance identity — no per-node config files required.

If a node runs the bare template directly (e.g. on a slot-detected Pi Zero W 2 where the node's identity comes from GPIO strapping), INSTANCE falls back to SLOT_ID from /run/schema-init/env. One SD card image serves the entire fleet.

AllowedSlot gate — for hardware deployments where running the wrong firmware on the wrong node is a physical hazard, add slot constraints to the template:

name=motor
exec=/usr/local/bin/motor-ctrl
allowed_slot_min=16
allowed_slot_max=27

If SLOT_ID is outside the declared range at spawn time, schema-init logs a HAZARD line, refuses the spawn, and sets SVC_NO_RESTART. The process never runs. Project Daedalus slot map:

Dependencies are resolved by name at load time. A service stays in NEW_PROCESS until all its deps reach FUNDAMENTAL, SETTLED, or PERFECT. A dep name can refer to either a service or a group (see below).

Drop a .grp file in the same services directory to create a named group. Services can depend on a group name just like a service name.

name=storage
member=lvm
member=cryptsetup
member=mount-data

A group's state is the worst-case view of its members:

• Any member EXCISED → group is EXCISED
• Any member in FRICTION/RECOVERY → group reflects that
• All members FUNDAMENTAL or better → group is FUNDAMENTAL
• All members PERFECT → group is PERFECT

Maximum 16 groups, 8 members per group. Names and members are matched at load time.

Add on_boot_sec and/or on_active_sec to any .svc to make it periodic — no separate .timer file, no second unit to link. The service is the timer. This replaces cron and systemd .timer units with the same .svc you already wrote.

name=fstrim
exec=/usr/sbin/fstrim
args=-a
needs_root=1
on_boot_sec=600        # first fire 10 min after boot
on_active_sec=86400    # then every 24 h after each completion

A timer is a oneshot that re-arms on a CLOCK_MONOTONIC deadline instead of staying terminal at PERFECT:

• It boots into PERFECT (as if it already ran), first fire at boot + on_boot_sec.
• On fire it re-enters NEW_PROCESS — so dependencies are still honored and it waits for its deps exactly like any service.
• When it exits, it re-arms for now + on_active_sec regardless of exit code (cron semantics — a failed run is not retried in a loop; it runs again next window). The exit is logged timer-done or timer-failed.

Run-once: set only on_boot_sec (leave on_active_sec unset) and the service fires exactly once, on_boot_sec seconds after boot, then stays terminal — a deferred startup job rather than a repeating one.

The period is measured from completion, so a slow job never overlaps itself. Fires on the 250 ms tick (±1 tick) — cron-class precision, not sub-second. For real-time work use watchdog_timeout_ms and the control loop instead.

Wall-clock timers — set on_calendar=HH:MM to fire at a fixed local time every day, the way you'd write a cron line. This is the form you want for "3am backup", "midnight log rotation", "nightly cert renewal":

name=nightly-backup
exec=/usr/local/bin/backup.sh
needs_root=1
on_calendar=03:00     # fire at 03:00 local time, every day

on_calendar re-evaluates the wall clock on every fire, so it tracks CLOCK_REALTIME (not monotonic) — DST shifts and NTP clock steps self-correct each cycle rather than drifting. Time is local (/etc/localtime). Malformed values (want HH:MM, 00:00–23:59) are logged and ignored, never scheduled.

Catch-up after downtime — by default a job missed while the machine was off simply runs at its next occurrence. Add persistent=1 to run it once at boot instead, if its scheduled time passed while the system was down (systemd Persistent=true):

name=nightly-backup
exec=/usr/local/bin/backup.sh
needs_root=1
on_calendar=03:00
persistent=1          # if 03:00 was missed while off, run at next boot

Last-run is stamped to /var/lib/schema-init/timers/<name>.stamp; at boot, if the most recent HH:MM occurrence is newer than that stamp, the timer fires immediately (logged timer-catchup) instead of waiting. A never-run timer is seeded rather than replayed, so enabling one doesn't trigger a surprise fire on first boot. persistent=1 only applies to on_calendar timers; on an interval timer it's logged and ignored.

Not yet implemented: richer calendar forms (day-of-week, multiple times per day). See docs/timers-design.md.

schema-init handles shutdown signals from userspace or the kernel:

sudo kill -TERM 1   # poweroff
sudo kill -INT 1    # reboot

On SIGTERM, schema-init sets system state to shutdown, sends SIGTERM to all child processes, waits 500ms for clean exit, then calls reboot(RB_POWER_OFF).

On SIGINT, same sequence ends with reboot(RB_AUTOBOOT).

The 500ms hold is intentional — it gives any running desktop or display manager time to render a shutdown state before the process tree is torn down.

These are real gaps, not future features being teased:

• No socket activation — services must manage their own sockets. There is no systemd-style socket hand-off (LISTEN_FDS).
• Log rotation needs a timer you schedule. The logrotate config ships; nothing here fires it. See Logs.
• schema-logind.py is a stub with one session object, not one per session. It implements enough of org.freedesktop.login1 for a Wayland compositor to take KMS and hand it back on a VT switch (see Recovery console), but it does not model multiple concurrent seats or sessions. It also does not set KDSKBMODE = K_OFF, deliberately — if the daemon died while K_OFF were set, the console keyboard would stay dead — so keystrokes can still leak to the tty underneath a compositor.

schema-init does not parse /etc/fstab. On boot it mounts the pseudo-filesystems directly:

After mounting /dev, schema-init creates four symlinks that devtmpfs does not provide and a userspace init is expected to make itself:

Without these, bash process substitution (< <(...)) and any /dev/stdin-style redirect fail — a gap that surfaces in ordinary shell scripts long before it surfaces anywhere in the init itself.

schema-init also creates /run/log/schema-init/ at boot. Each service's stdout and stderr are redirected there automatically (see Logs).

If your system needs additional mounts (data partitions, network filesystems), run them as oneshot services before your other services depend on them.

Mount by UUID= or LABEL=, never /dev/sdX. The kernel assigns sda/sdb/… in detection order, which can change between boots — so a oneshot that mounts /dev/sdb1 may silently land on the wrong physical disk, swapping two data drives and pointing every absolute path at the wrong filesystem. /etc/fstab under systemd hid this by mounting by UUID for you; schema-init doesn't read fstab, so do it explicitly: mount UUID=1b7d654f-… /mnt/data (or LABEL=). The same applies to the root LABEL=/PARTUUID= on the kernel cmdline.

make

Produces a fully static binary — no glibc version dependency, runs on any Linux kernel. Tested on:

• Debian Bookworm, kernel 6.1, x86_64 — headless and Cinnamon desktop
• Fedora 44, kernel 7.0, x86_64 — full KDE Plasma desktop, btrfs subvolume boot

Cross-compile for aarch64 (ARM — Ungulate Leg target):

make aarch64

Requires aarch64-linux-gnu-gcc. On Fedora: sudo dnf install gcc-aarch64-linux-gnu. Produces static schema-init-static, schema-ctl, and schema-subreaper binaries. Override sysroot with SYSROOT=/path/to/sysroot make aarch64.

ARM bare-metal (Pi Zero W, armv6l):

Fedora's arm-linux-gnu-gcc cross-compiler does not ship an arm sysroot. Compile natively on the Pi:

sudo apt install git gcc make
git clone https://github.com/ajax80/schema-init
cd schema-init && make

The armhf Makefile target exists for environments that have a full arm sysroot available.

schema-desktop (optional SDL2 monitor):

make desktop
sudo cp desktop/schema-desktop /usr/local/bin/schema-desktop

Requires SDL2 and SDL2_ttf. On Fedora: sudo dnf install SDL2-devel SDL2_ttf-devel. Reads live service state from PID 1's shared memory segment — run it from the desktop after login, or drop distros/*/config/autostart/schema-desktop.desktop into ~/.config/autostart/ to launch it automatically.

# install as PID 1 — symlink approach (distro-compatible)
cp schema-init /sbin/schema-init
ln -sf /sbin/schema-init /sbin/init

# or pass to kernel directly via GRUB
linux /boot/vmlinuz root=LABEL=my-root init=/sbin/schema-init

Option A — symlink (/sbin/init → /sbin/schema-init): works with any distro GRUB config, no kernel cmdline change needed. Replace your distro's init binary or point the symlink.

Option B — explicit init= in GRUB: add init=/sbin/schema-init to the kernel line in /etc/default/grub, then grub-mkconfig -o /boot/grub/grub.cfg (Debian/Ubuntu) or grub2-mkconfig -o /boot/grub2/grub.cfg (Fedora).

Option C — custom GRUB menu entry: create a separate entry that leaves the distro default untouched:

# /boot/grub/custom.cfg  (included automatically by grub.cfg)
menuentry 'schema-init' {
    search --no-floppy --label --set=root schema-root
    linux   /boot/vmlinuz-$(uname -r) root=LABEL=schema-root rw quiet init=/sbin/schema-init
    initrd  /boot/initramfs-$(uname -r).img
}

Option C is the safest for dual-boot or first-time installs — it leaves the existing systemd entry intact as a fallback.

Kernel cmdline words are safe. The kernel hands PID 1 every boot-cmdline token it didn't consume (rhgb, quiet, splash, plymouth.debug, …), so leave your usual options in the kernel line — schema-init ignores them when it runs as PID 1. A services directory other than the default /etc/schema-init/services can only be set by hand-running the binary (schema-init /path/to/services), never via the kernel cmdline.

The init binary cannot be overwritten while running (text file busy). Use the copy-then-move trick:

cp schema-init /sbin/schema-init.new
mv /sbin/schema-init.new /sbin/schema-init

mv replaces the directory entry atomically without touching the inode that the kernel holds open. The new binary takes effect on next boot.

Tested on Dell Inspiron 3542 (Intel Core i3, 4GB RAM) running full Cinnamon desktop:

The gap is structural. schema-init spawns your services and then sits in a 250ms tick loop. There is no journal daemon, no dbus-broker, no socket activation layer, no unit file parser running in the background.

Boot timing breakdown (Dell Inspiron 3542, Debian Bookworm, kernel 6.1.0-49, times relative to PID1 start):

kernel → PID 1:    6.968s
dbus               1.761s   (ready: /run/dbus/system_bus_socket)
elogind            2.739s   (ready: /run/systemd/seats)
polkitd            3.447s
udev               3.197s
network           10.505s   (oneshot)
network-manager   11.757s
getty-tty1        10.755s
sshd              10.755s
display-manager   13.760s   ← LightDM login screen visible

total kernel → login screen: ~20.7s

schema-ctl timing produces this output.

One table, every number, each naming the machine, the build and the service count it came from. Anything not listed here is not a measurement we have.

On the same kernel and QEMU profile that is 8–17× lighter. The desktop and the Cloud Base figures are not a fair pair — one runs KDE, the other is headless — so they are not presented as one. The only apples-to-apples comparison here is minimal-boot schema-init vs clean-idle systemd.

Two numbers this README used to carry, and why they're gone:

• "892 KB" was real, but it was an earlier and smaller build on the Dell. Current builds measure 1.2 MB minimal and 3.3–4.0 MB at a full desktop; the init has grown (timers, cpuset, cgroup delegation, container support). Leading with the lowest figure ever recorded, from a binary you can no longer download, isn't a footprint claim — it's cherry-picking. 892 KB was also never the binary's size on disk (see Binary size).
• "40 MB – 120 MB" for systemd's PID 1 was never measured by this project. The measured figure is 20.1 MB, above.

make produces an unstripped static binary. Measured on the v0.1.0 build (601b18ac, 2026-07-24):

.text alone is 1.1 MB, so no build of this binary has ever been under 1 MB on disk. Reproduce with ls -l, size and strip. Note that plain make does not strip — quote 5.6 MB for what you build yourself, 1.2 MB only for a stripped binary. make release produces the stripped set in release/ alongside a SHA256SUMS file; that is what release assets ship.

Live measurements from a 9-hour uptime session (Fedora 44, KDE Plasma, GreyBox — note this node runs an older, smaller build; its RSS is not comparable to the current one):

The load average on an idle system with schema-init as PID 1 sits at 0.03. On the same hardware with systemd, ambient timer wakeups hold it at 0.10–0.20 at idle. The difference is structural: schema-init's tick loop sleeps indefinitely once all services are stable. Nothing wakes it.

turbostat on Eli (Dell Inspiron 3542, Intel i3-4005U, Fedora 44, full Cinnamon desktop):

C10%: 92–99%    ← deepest available C-state; CPU hardware-verified
C6%:  0.00%     ← skipped; CPU goes straight to C10
Busy: 0.21–0.38%
PkgWatt: 1.23–1.32W   ← entire SoC including iGPU, read via Intel RAPL
GFX%rc6: 99.67%        ← integrated GPU in deepest sleep state

C10 is the deepest sleep state on Haswell silicon. Reaching it requires the CPU to sit undisturbed long enough to flush caches and power-gate internal voltage rails — typically blocked by the constant timer wakeups from systemd's watchdog, journal flush, and D-Bus polling infrastructure. At 92–99% C10 residency with a full desktop running, schema-init is generating near-zero ambient noise. The 1.25W package figure is read directly from Intel RAPL hardware energy counters, not estimated. Services with ready_path set promote the instant the path exists — no blind timer. stable_secs (default 10s) is the fallback. The remaining ~10s cluster is network/getty/sshd with no readiness path.

schema-ctl is a control client that communicates with the running init over a Unix domain socket at /run/schema-init.sock.

sudo schema-ctl status          # full state dump for all services
sudo schema-ctl status --json   # machine-parseable JSON — for supervisory loops and IEC 62304 audit
sudo schema-ctl status --kv     # flat key=value — grep-friendly
sudo schema-ctl list            # names and current states only
sudo schema-ctl start <name>    # start a stopped or EXCISED service
sudo schema-ctl stop <name>     # send SIGTERM to a running service
sudo schema-ctl restart <name>  # stop + re-queue through the state machine
sudo schema-ctl add <path>      # load a new .svc file at runtime, no reboot needed
sudo schema-ctl reload          # re-read the services directory (rejected if new config has a cycle)
sudo schema-ctl reload --evict  # reload + SIGTERM any running service no longer present in config
sudo schema-ctl pet <name>      # service heartbeat check-in — resets watchdog_timeout_ms window
sudo schema-ctl reset [<name>]  # reset restart/dormant counts and re-queue failed services

The socket is chmod 0600 — root only. Build alongside the init binary:

make schema-ctl
sudo cp schema-ctl /usr/local/bin/schema-ctl

When a Wayland compositor wedges, ctrl-alt-F2 only gets you another login on the same broken session, and systemd's rescue/emergency targets are all-or-nothing — they tear the session down and lose your work. schema-board on a dedicated VT is the alternative: a surface that sits below the compositor and shows you what is actually wrong.

schema-board --tty /dev/tty8      # then ctrl-alt-F8 to look at it

It reads the shared-memory export rather than the control socket and depends on nothing graphical, so a frozen desktop, a wedged control socket, and a saturated D-Bus all leave the process working. Give it a VT no getty owns — services/ ships gettys on tty2–tty6, and tty1 is the display manager, so tty7 and up are free.

✅ VT switching works on a graphical schema-init system. This was broken until 2026-07-26 and is now fixed in scripts/schema-logind.py. Confirmed on real hardware — NVIDIA, sddm-started KDE Wayland session — by a human looking at the screen, which is the only evidence that settles a question about what is visible.

The wedged case is what the recovery console exists for, and it is the fail-safe that carries it. With the compositor SIGSTOPed it cannot answer PauseDeviceComplete, so every device ack goes missing. Releasing the VT anyway — rather than waiting for acks that will never arrive — is the only reason the switch completes:

VT release requested — pausing 10 device(s)
DROP_MASTER ok on fd=11
10 device ack(s) missing — releasing anyway
VT_RELDISP(1) — switch allowed to proceed

Blocking there would strand the kernel mid-switch with DRM master already dropped: a black screen with no way back. On SIGCONT the compositor flushes all ten acks and a late Seat.SwitchTo for the keypress it was frozen on, and the session recovers. Note that in the wedged case the kernel drives the handoff alone through VT_PROCESS — Seat.SwitchTo arrives after the release, not before it as in the healthy case. That is the difference a polling implementation cannot cover.

A graphical session needs this chain, and every link now exists:

ctrl-alt-F<n>
  → kernel signals schema-logind (VT_PROCESS) and WAITS   ✅ VT_SETMODE at TakeControl
  → logind sends PauseDevice to the compositor            ✅ pause, per device taken
  → logind drops DRM master                               ✅ DRM_IOCTL_DROP_MASTER
  → logind acks with VT_RELDISP, kernel completes switch   ✅
  → fbcon restores the mode with master already free      ✅ console repaints
  → on return: VT_RELDISP(VT_ACKACQ), SET_MASTER, ResumeDevice

VT_PROCESS mediation is the load-bearing part, and a polling implementation cannot replace it. An earlier fix watched /sys/class/tty/tty0/active every 250 ms and implemented PauseDevice/ResumeDevice, VTNr, and Seat.SwitchTo — all necessary, none sufficient. The kernel completes a VT switch synchronously, and fbcon's mode restore runs during it, while master is still held; it fails silently and is never retried. Measured: after the poll dropped master the console sat at 15 non-black pixels, and a second switch — master already free — painted 32,771. The active-VT poll survives only as a fallback for when VT_SETMODE fails.

Two things this depends on, both worth knowing before you touch it:

• ReleaseControl restores VT_AUTO. KWin calls it from ~LogindSession. Anything that takes control and exits — a display-manager greeter, for instance — tears mediation down for whoever comes next.
• The chord arrives twice, once from the kernel's VT handler and once from the compositor calling Seat.SwitchTo for the same keypress. Handling it twice overwrites and leaks the pending-ack timer.

Two earlier revisions of this section were wrong in ways worth recording. The first blamed a stopped compositor for being unable to release DRM master; a healthy one does not release it either, because nothing asks. The second proposed having the board take DRM master itself, which cannot work — DRM_IOCTL_SET_MASTER fails while another process holds master. The real cause was that Properties.Get for VTNr failed, so KWin's LogindSession::create() bailed and it silently fell back to NoopSession, whose switchTo() is an empty function body.

On a machine with no graphical session — a server, a Pi, an initramfs-less boot before the display manager starts — the recovery console works regardless, because nothing has taken KMS.

If you are stranded on an invisible VT, sudo chvt 1 from any other shell (ssh included) puts you back.

To have PID 1 own it from boot, copy services/schema-board.svc.example into /etc/schema-init/services/:

name=schema-board
exec=/usr/bin/schema-board
args=--tty
args=/dev/tty8
needs_root=1
critical=0

Two things about that file are load-bearing:

• args= is one argument per line. args=--tty /dev/tty8 on a single line passes one argv of "--tty /dev/tty8", which schema-board rejects. Repeat the key.
• --tty is not optional for a service. Services are spawned with stdout redirected to /var/log/schema-init/<name>.log, so without --tty the board would faithfully paint its frames into a logfile.

On the console it takes over, the board disables screen blanking and hides the cursor, restoring the cursor when it exits.

sudo schema-ctl status          # full dump: state, pid, restart count, weight
sudo schema-ctl list            # compact: name + state only
sudo schema-ctl timing          # kernel→PID1 handoff + per-service stable timestamps

A service stuck in NEW_PROCESS means its dependencies haven't stabilised. status shows the state of every dep — trace upward.

A service in FRICTION is in last-chance recovery. On the next failed F6 probe it enters DORMANT (exponential backoff) rather than going straight to EXCISED. Use sudo schema-ctl start <name> to manually re-queue it immediately instead of waiting out the backoff.

tail -f /run/log/schema-init/<name>.log    # live stdout/stderr for a service
cat /run/log/schema-init/dbus.log          # full output since last boot

These are plain text on a tmpfs. If a service is failing silently, its output is here.

If a desktop application hangs for exactly 25–30 seconds, D-Bus auto-activation is timing out trying to reach an unregistered interface. Trace it:

dbus-monitor --system 2>&1 | grep -A4 "method call"

The culprit will appear as a method call to a destination=org.freedesktop.SomeName that produces no method return for ~25 seconds.

Fix options:

1. Register the interface — see schema-logind for the pattern
2. Mask the activation file: sudo rm /usr/share/dbus-1/system-services/<name>.service

If schema-init drops to a rescue shell at boot (cycle detected, or fatal probe failure), you have a minimal /bin/sh with access to the mounted filesystems. From there:

# inspect service files
ls /etc/schema-init/services/
cat /etc/schema-init/services/broken.svc

# fix and re-exec
vi /etc/schema-init/services/broken.svc
exec /sbin/schema-init

Init log — schema-init writes spawn/promote/death events to stdout, which the kernel connects to the console at boot. To persist:

exec /sbin/schema-init >/var/log/schema-init.log 2>&1

Per-service logs — each service's stdout and stderr are captured automatically to:

/var/log/schema-init/<name>.log        # preferred (persists across boots)
/run/log/schema-init/<name>.log        # fallback when /var is not writable (tmpfs, per-boot)

To read them while the system is running:

tail -f /var/log/schema-init/dbus.log
tail -f /var/log/schema-init/network-manager.log

There is no journal daemon. Logs are plain text, always.

Rotation — schema-init.logrotate is installed to /etc/logrotate.d/schema-init (weekly, or sooner at 100 MB, keeping 4 compressed generations). It uses copytruncate, and that is not optional:

• A service's log fd is opened in the child before exec (service.c:321) and held for the whole life of the process. Renaming the file would leave every running service appending to the old inode — the new file would stay empty until the service restarted.
• SIGHUP to PID 1 means reload configuration (init.c:1312), not "reopen logs". A postrotate kill -HUP 1 would silently trigger a config reload instead of rotating.
• Every writer uses O_APPEND (service.c:321, schema-journal-sink.c:344), which is what makes truncation safe: writes resume at offset 0 instead of leaving a sparse hole at the old offset.

Something has to run logrotate. There is no cron and no logrotate.timer here, so schedule it as an ordinary wall-clock timer — see services/logrotate.svc.example:

name=logrotate
exec=/usr/bin/logrotate
args=/etc/logrotate.conf
needs_root=1
on_calendar=00:10

Without that timer (or some other caller) the config sits inert and logs still grow unbounded.

journalctl shim (optional Track B) — software and post-install scripts that shell out to journalctl -u <svc> would fail with no journald present. scripts/journalctl is a drop-in interceptor: install it to /usr/local/bin/journalctl and it serves the matching *.log from the directories above, swallows unknown flags, supports -o json, and always exits 0 so a caller piping it to jq/awk never hard-crashes. It does not read a binary journal — there isn't one.

Running processes can read service state via POSIX shared memory at /schema-init:

#include "schema_shm.h"

int fd = shm_open("/schema-init", O_RDONLY, 0);
schema_shm_t *shm = mmap(NULL, sizeof(schema_shm_t), PROT_READ, MAP_SHARED, fd, 0);

for (int i = 0; i < shm->count; i++) {
    printf("%s state=%d weight=%d pid=%d\n",
           shm->svc[i].name,
           shm->svc[i].state,
           shm->svc[i].weight,
           shm->svc[i].child_pid);
}

On a no-systemd desktop, several interfaces are missing that desktop environments expect. schema-logind (distros/*/services/schema-logind.svc) handles the session/power/host interfaces in a single Python process on the system bus. The org.freedesktop.systemd1 management surface is served by its own process — see below.

Without these stubs, KDE and GNOME panels hit the D-Bus default timeout (25–30s) before giving up. With them, the same queries return in <100ms.

D-Bus policy required. The systemd-shipped org.freedesktop.login1.conf policy denies all non-root calls to login1 by default — KDE and Cinnamon will never see the power buttons without a drop-in. Install the one from this repo:

sudo cp distros/shared/dbus/schema-logind.conf /etc/dbus-1/system.d/schema-logind.conf
sudo dbus-send --system --type=method_call --dest=org.freedesktop.DBus \
    /org/freedesktop/DBus org.freedesktop.DBus.ReloadConfig

Then log out and back in (or reboot). The policy whitelists CanPowerOff, CanReboot, PowerOff, Reboot, and all session/seat methods schema-logind exports.

schema-logind is not a dependency of schema-init itself — it is a userspace service like any other. Drop its .svc file in your services directory and list it as a dep of your display manager:

name=sddm
exec=/usr/sbin/sddm
dep=dbus
dep=schema-logind
dep=polkitd
needs_root=1

The real systemd1 surface (schema-systemd1). Unlike the read-only stubs above, org.freedesktop.systemd1 is served by its own process (services/schema-systemd1.svc → scripts/schema-systemd1.py), not schema-logind. It registers every schema-init unit as a …/unit/<name>_2eservice object and mirrors live state from schema-ctl, so systemctl status <svc> and Cockpit's Services page show real ActiveState/SubState/MainPID/restart counts — and StartUnit/StopUnit/RestartUnit drive schema-ctl for real. Unit names are validated before being handed to schema-ctl (argv/newline injection guard). State transitions emit PropertiesChanged, so Cockpit updates without a refresh. Design notes: docs/superpowers/specs/2026-06-20-schema-systemd1-dbus-design.md.

The sd_booted() signal. mount_pseudo() creates /run/systemd/system at early boot (init.c). libsystemd's sd_booted() is a bare access() on that path, so any software gated on "is systemd the init?" — KService/ksycoca, elogind clients — gets a positive answer with no shim. This is what made the old LD_PRELOAD mock_sd.so workaround (which faked the check to stop KDE's ksycoca from spinning at idle) unnecessary: the signal is now native and costs one mkdir.

The sd_login_monitor directories. libsystemd's sd_login_monitor_new(NULL, …) — used by WirePlumber's logind module and other session/seat-aware clients — sets an inotify watch on /run/systemd/{sessions,seats,users,machines}. If any of those directories is missing the call fails with -ENOENT and the client silently drops logind integration (for WirePlumber that means no device reservation, no session-based pause). schema-logind creates all four at startup, empty — matching what real logind does even with no active sessions — so those clients initialize cleanly. Costs four mkdirs.

Starting from scratch on a distro not in distros/:

1. Build the binary on the target (or cross-compile):

git clone https://github.com/ajax80/schema-init
cd schema-init && make

2. Install:

sudo cp schema-init /sbin/schema-init
sudo cp schema-ctl  /usr/local/bin/schema-ctl
sudo mkdir -p /etc/schema-init/services

3. Write service files. Start minimal — just enough to reach a console:

# /etc/schema-init/services/udevd.svc
name=udevd
exec=/usr/lib/systemd/udevd
args=--daemon
needs_root=1
stable_secs=3

# /etc/schema-init/services/dbus.svc
name=dbus
exec=/usr/bin/dbus-daemon
args=--system
args=--nofork
needs_root=1
stable_secs=2
ready_path=/run/dbus/system_bus_socket

The udevd path varies by distro: /usr/lib/systemd/udevd (Fedora/Debian), /lib/udev/udevd (older Debian), /usr/bin/udevd (Arch).

4. Configure GRUB (see Building → GRUB setup above). Boot with a fallback entry pointing at systemd so you can recover.

5. Boot and check:

sudo schema-ctl list       # all services should reach FUNDAMENTAL
sudo schema-ctl timing     # see where time goes
tail /run/log/schema-init/udevd.log   # if something is EXCISED, check its log

6. Add services incrementally. Bring up network, then login manager, then display manager. Add dep= links to enforce order. Add ready_path= for anything with a socket or pidfile.

7. Handle D-Bus hangs. Open your desktop's settings panel immediately after first login. If it hangs >5s, run dbus-monitor --system and identify the missing interface. Add a stub to schema-logind or mask the activation file.

Common issues by distro:

Working configurations for specific distros and desktops live in distros/.

Full KDE Plasma 6 desktop on Fedora 44 with schema-init as PID 1. Boots from a btrfs subvolume alongside a normal Fedora install — no repartitioning required.

What's running:

See distros/fedora-kde/README.md for full installation instructions and key fixes.

WiFi headless deploy on a Pi Zero W (BCM2835, armv6l, 32-bit ARM). No Ethernet, no HDMI — schema-init as PID 1, WiFi up, SSH accessible in ~50 seconds from cold boot. First ARM bare-metal target.

Service chain:

See distros/raspberry-pi-zero-w/README.md for the full list of gotchas (rfkill country code, dbus privilege drop, coldplug trigger, dhcpcd forking behavior) and installation steps.

• Runtime service loading — schema-ctl add <path> loads a new service at runtime
• Runtime reload + removal — schema-ctl reload [--evict] re-reads config (cycle-checked); --evict SIGTERMs services dropped from config, no reboot
• login1 D-Bus stub — schema-logind restores KDE shutdown/restart buttons on no-systemd systems
• event-driven main loop — signalfd for SIGCHLD + poll() with 250ms timeout; wakes on child death and ctl commands instead of busy-polling
• Boot hang fix — dep_idx alignment bug in group dep resolution; poll() replaces epoll (PID 1 epoll deadlock on kernel 6.1.0-49)
• Boot timing — schema-ctl timing reports kernel→PID1 handoff and per-service FUNDAMENTAL/PERFECT timestamps (CLOCK_MONOTONIC)
• Boot time measurement — 29.5s → 20.7s with ready_path probes; stable_secs fallback per service
• Per-service readiness probes — ready_path= promotes on path existence; stable_secs= fallback timer
• Cgroup assignment race fix — pipe barrier guarantees cgroup.procs written before child exec
• Dynamic poll timeout — loop sleeps indefinitely once all services stable; 0% CPU idle
• Service log files — stdout/stderr per service at /run/log/schema-init/<name>.log
• D-Bus stubs — hostname1 and systemd1 Manager stubs in schema-logind; KDE Settings 25s → 2s
• Fedora KDE distribution — GreyBox daily driver, full KDE Plasma 6 on Fedora 44
• Fedora Cinnamon distribution — Eli (Dell Inspiron), keyboard/touchpad/ethernet working
• STATE_DORMANT (75) — exponential backoff before 76 verdict; critical services never excise
• Soft dep cascades — non-critical EXCISED deps skipped; dependents proceed without them
• aarch64 cross-compile — make aarch64; all three binaries static; Ungulate Leg target ready
• ARM bare-metal deploy — Pi Zero W (armv6l), Pi OS Trixie; SSH up in ~50s from cold boot
• schema-desktop — SDL2 live service viewer; make desktop + autostart entry in Cinnamon and KDE distros
• Dead Man Token hardware watchdog — /dev/watchdog driven by per-service check-in via schema-ctl pet; any critical service missing its watchdog_timeout_ms window stops WDT petting → hardware reboot; PID 1 deadlock covered implicitly
• Symlink template instances — motor@12.svc → motor@.svc; $INSTANCE injected at spawn; $SLOT_ID fallback for GPIO-strapped nodes; one SD card image per fleet
• Structured telemetry — schema-ctl status --json and --kv for machine-parseable supervisory loop consumption and IEC 62304 audit traceability
• Cgroup resource limits — cpu_limit= (1–100, % of one core), mem_limit= (MB), cpuset= (CPU affinity / core pinning, systemd AllowedCPUs= analog), and cpuset_partition= (isolated/root exclusive cores via cgroupv2 partitions — dynamic isolcpus) per .svc; written via sync-pipe window before child exec; IEC 62304 Class C blast-radius isolation
• zram swap — zram-swap.svc boots a zstd-compressed zram swap device, replacing systemd's zram-generator; eliminates disk thrashing / periodic stutter under memory pressure

schema-init was built by Jonathan Ayers in 2026 as the operating layer for the Ungulate Leg — an exoskeleton controller that needs a deterministic, schema-driven PID 1 carrying none of systemd's assumptions about what a computer is for. (A sister project, the Samara Wing, applies the same architecture to flight.) The reference hardware that proved it — a pawn-shop Dell Inspiron named Eli — booted to a full desktop under schema-init on May 30th, 2026. It was written alongside Claire, an AI (Claude, by Anthropic) that held continuity across the work.

AGPL-3.0-or-later for open source use — full text in LICENSE.
Commercial license available for embedding in proprietary systems — open an issue or contact via GitHub.

Built by Jonathan Ayers. The schema was written before the code.