RFC — OS Update Mechanism (koder-os-update)

Version: 0.1.0 — Draft Status: Proposed (20260520) Owner: Koder Linux WG (infra/linux/distro) Discussion ticket: infra/linux/distro #018

Abstract

Installed Koder Linux currently has no first-class "system update" path. Users can run apt upgrade packagebypackage (no awareness of which upgrades are OSrelevant) or reflash the ISO (loses local state). This RFC defines the koder-os-update CLI, picks the transport, and lays out the rollout from v0 (aptonly over Hub) to v1+ (rollbackcapable, likely ostree or A/B partitions). It explicitly does *ot*specify a kolide notification UX (that is a separate Kolide ticket) or perapp autoupdate (specskoder-appbehaviors.kmd §4 already covers that — different scope).

Motivation

Today's gap

1. *iscoverability:*the user has no command that answers "is my system

   up to date?" Perpackage `apt list -upgradable` is too noisy and doesn't distinguish OS-relevant updates from random Debian packages.

2. *tomicity:*apt upgrade midflight can leave a halfupgraded

   kernel + initramfs pair if power is cut. No rollback.

3. *eproducibility:*policies/releases.kmd tags every component for

   per-component release engineering, but the OS itself (kernelglibc systemd + all koder-suite packages from hook 0060) doesn't have a "Koder Linux release" version anywhere a running install can see.

4. *X:*specs/koder-app/behaviors.kmd §4 made per-app updates a

   smooth, default-ON background process. The OS update story should feel equally low-effort, not "drop to a terminal and remember 4 commands".

Why now

Three of the four blockers for the simplest viable transport just shipped (20260519): products/dev/hub #116 (apt surface), #117 (GPG signing key), and #103 (Flow→Hub publish pipeline) are all in backlog/done/. That makes apt-get install -y koder-os-update; apt-get update; apt-get upgrade a 30line shipinweeks v0, vs. weeksto-months for any rollback-aware design. Shipping v0 now buys us a tracker for what "upgrade-friction" actually looks like in the field, which is the information we need to size v1 properly.

Candidate transports

Three concrete options were considered. Each is scored against five criteria taken from policies/self-hosted-first.kmd + Koder Linux specifics: implementation cost, rollback story, bandwidth efficiency, operational complexity, and migration risk away from this choice later.

Option A — apt-only over Koder Hub (Recommended for v0)

hub.koder.dev/apt already serves the canonical koder-* packages under suites stablepredev (per hub #116, #117, #131). A koder-os-update CLI is a thin wrapper:

• check → apt-get update -q && apt-get -s upgrade filtered to a

  curated OS-RELEVANT_PACKAGES=(linux-image-* initramfs-tools dracut systemd glibc dbus kolide-* koder-* …) list.

• apply → apt-get install --only-upgrade -y <filtered list> +

  postupgrade hooks (`updateinitramfs u, updategrub`).

• rollback → not supported in v0; prints

  "rollback requires ostree mode (see RFC §A/B partitions); v0 workaround: reinstall the previous .deb via 'apt install <pkg>=<old_version>'".

Pros:

• Ships in ~2 weeks. CLI is mostly argument parsing + apt wrappers.
• Reuses every piece of infrastructure we just shipped (#116#117#103).
• Zero new daemons, zero new on-disk layout changes.
• Plays well with policies/multi-tenant-by-default.kmd — apt's lock is

  one writer at a time, which matches existing semantics.

Cons:

• *o atomic apply.*Power loss mid-upgrade can leave a broken kernel

  + initramfs pair. Mitigation: do kernel + initramfs *ast*in the apply order, after all userspace upgrades. Documents the risk; doesn't solve it.

• *o rollback.*Documented as a known v0 limitation with a v1 plan.
• Not all OS-relevant state lives in .deb packages (e.g. NetworkManager

  config drift, custom systemd overrides). v0 simply won't touch those.

Score: cost 15 (~2 weeks); rollback 45 (no); bandwidth 3/5 (apt's deltadebs help but no chunklevel dedup); ops 2/5 (familiar shape); migration 2/5 (v0 → v1 is additive — koder-os-update CLI keeps the same surface, only transport swaps under it).

Option B — ostree (Atomic-style, immutable rollback)

Reorganise the rootfs so /usr is a versioned tree on libostree, with the running system being a deployment checkout. Same model as Fedora Silverblue, CoreOS, EndlessOS.

Pros:

• True atomic upgrade: deploy a new tree, reboot into it. Old tree

  stays on disk for one-keystroke rollback.

• Tree integrity is contentaddressed — no halfstate windows.
• Diff between two deployments is precise (single chunk graph).
• Fits well with the future Koder Linux server use case (s.khost*

  fleet management).

Cons:

• *ilesystem reorganisation.*/usr rdonly breaks the

  "edit etckoder-linux