veilor-os/docs/STRATEGY.md

# veilor-os Strategy — Hybrid kickstart bootstrap + bootc OCI

Decision date: **2026-05-05**
Locked at: **v0.5.31 → v0.7 spike → v1.0**

## TL;DR

- Keep the Anaconda-driven kickstart ISO as the **bootstrap installer**
  (LUKS UX is mature, single passphrase prompt, custom partitioning
  works).
- On first boot, the installed system is automatically rebased to a
  **veilor-os OCI image** built via BlueBuild on top of secureblue's
  `securecore-kinoite-hardened-userns`.
- All future updates flow through `bootc upgrade` — atomic A/B,
  instant rollback, cosign-signed.
- The kickstart-driven mutable-root path is deprecated at v1.0; kept
  alive as fallback through v0.7.

## Why hybrid, not pure pivot

Pure pivot to bootc-from-scratch (Agent 3's spike plan) was **1 week
to first ISO**. Pure pivot to layering on secureblue is **2 days to
first ISO** because the hardening work is already done. But both
require throwing away the partitioning UX we already have working in
Anaconda.

Hybrid:
- **Day-zero install:** Anaconda kickstart + custom partitioning +
  LUKS prompt (what we have today). User experience = unchanged.
- **First boot, post-LUKS-unlock:** `bootc rebase
  ghcr.io/veilor/veilor-os:43` runs once; pulls the OCI image; next
  reboot lands in the veilor OCI tree.
- **Day-2:** `bootc upgrade` cadence for everything from then on.

We keep what works, pivot the part that doesn't.

## Why secureblue underneath

| Question | Answer |
|---|---|
| Maintainers | secureblue: 30 contributors, 56 commits/5wks. veilor-os: solo. |
| Hardening surface | secureblue ships sysctl + kargs + SELinux + USBGuard + hardened-malloc + DoT — far more than we'd build alone. |
| Build pipeline | BlueBuild → cosign-signed OCI in GH Actions (`build-all.yml`, `trivy.yml`). |
| Update model | bootc upgrade with A/B + instant rollback + signed image chain. |
| Variants | `kinoite-hardened-userns` is the KDE+Wayland+SELinux variant we'd want. |
| License | Apache-2.0 (compatible with our MIT). |

What we override in our recipe:

- **Browser**: Trivalent (their fork) → Brave / Mullvad-Browser.
  Single-maintainer browser fork is unacceptable risk for daily-driver
  audience.
- **`run0` instead of sudo**: revert. Breaks too many workflows.
- **Xwayland disabled**: revert. Some apps still need it.
- **veilor branding**: theme, KDE color scheme, Plymouth, SDDM, font,
  os-release. All `overlay/*` ports verbatim from current repo.

## Strategic credibility win

secureblue does NOT publish a threat model. Athena OS does, and it's
their main differentiator. We've already drafted
`docs/THREAT-MODEL.md` (Agent 5 of 2026-05-05 wave). Publishing that
*before* the v0.7 launch positions veilor-os ahead of secureblue and
Athena on the one axis that matters most for a security-branded
distro: **honest, scoped, public threat model**.

## Roadmap implications

| Version | Status | Path |
|---|---|---|
| v0.5.31 | shipped | Anaconda kickstart, mutable root |
| v0.5.32 | active — top blockers from 9-agent wave | Anaconda kickstart |
| v0.5.x → v0.6 | maintenance | Anaconda kickstart, ergonomics + UX polish |
| **v0.7 spike** | **2-day BlueBuild prototype** | First veilor OCI image extending secureblue-kinoite-hardened |
| v0.7 ship | ISO bootstraps install, first boot rebases to OCI | Hybrid path live |
| **v1.0** | **bootc-only**, kickstart deprecated | `bootc upgrade` for all updates |

The `bootc-image-builder` spike plan (Agent 3) is **superseded** by
this hybrid: don't build a Containerfile from scratch on
`fedora-bootc:43`. Instead, write a BlueBuild recipe on
`securecore-kinoite-hardened-userns`. Spike compresses 1 week → 2 days.

## Next concrete steps

### v0.5.32 — current (no strategy change)

Ship the 7 blockers from `docs/research/2026-05-05-agent-wave/`:
suspend/resume wifi fix, firstboot WantedBy, USBGuard id-rules,
firewalld tailscale0 zone, KMS modeset, /etc/skel branding, virtio-9p
log capture.

### v0.7-spike (2 days)

1. New repo dir: `bluebuild/recipe.yml`.
2. `from`: `ghcr.io/secureblue/securecore-kinoite-hardened-userns:latest`.
3. Override modules:
   - `type: files` — stamp our `overlay/*` tree (branding, themes,
     veilor scripts, sddm theme, plymouth theme).
   - `type: rpm-ostree` — install Brave + restore Xwayland.
   - `type: rpm-ostree` — remove Trivalent.
   - `type: brand` — PRETTY_NAME, GRUB_DISTRIBUTOR, distributor URL.
4. `.github/workflows/build-bluebuild.yml` — pull BlueBuild action,
   build + cosign sign + push to GHCR.
5. `kickstart/install.ks` — add a one-shot `veilor-firstboot-rebase`
   service that runs `rpm-ostree rebase ghcr.io/veilor/veilor-os:43`
   then disables itself. User reboots once and is on the OCI image.

### v1.0 — bootc-only

- Drop `kickstart/veilor-os.ks`, drop `livecd-creator` workflow.
- Keep `installer-iso.toml` for the bootstrap ISO (built via
  bootc-image-builder); the OCI image is the source of truth.
- `veilor-update` becomes thin `bootc upgrade --apply` wrapper.

## Open questions

- Does secureblue accept upstream contributions? If yes, send our
  USBGuard id-based-rules fix and our threat model framework.
- Brave vs Mullvad-Browser: Brave has telemetry concerns out of box;
  Mullvad-Browser is Tor-Browser-derived but not designed for
  daily-driver. Test both in spike.
- Recovery flow when bootc rebase fails on first boot — need fallback
  to keep the kickstart-installed system bootable. Likely already
  handled by bootc's A/B; verify in spike.
- Fedora 44 transition: secureblue tracks Fedora releases (current
  `v4.9` on F44). If we follow, we get F44 for free at the same time
  upstream does.

## See also

- `docs/THREAT-MODEL.md` — drafted, needs publish for v0.7
- `docs/ROADMAP.md` — to be updated to reflect this strategy
- `docs/research/2026-05-05-agent-wave/03-bootc-spike-plan.md` —
  superseded by this hybrid (kept as reference for the
  Containerfile-from-scratch alternative)
- secureblue: <https://github.com/secureblue/secureblue>
- BlueBuild: <https://blue-build.org>