feat(steamframe): probe the Frame device layer against our nixpkgs #1650

Open
lytedev wants to merge 20 commits from propose/steamframe-phase0 into main
Owner

Phase 0 of #1648: both aarch64 probes evaluate against our nixpkgs-unstable with the Frame device layer applied. Read the commit for the four integration points it found (steamos uid 1000, the hardcoded primary group, and the two bootloaders).

Phase 0 of #1648: both aarch64 probes evaluate against our nixpkgs-unstable with the Frame device layer applied. Read the commit for the four integration points it found (steamos uid 1000, the hardcoded primary group, and the two bootloaders).
feat(steamframe): probe the Frame device layer against our nixpkgs
Some checks failed
/ check-format (push) Successful in 18s
/ build (push) Failing after 2m20s
6c85f7e10c
Phase 0 of issues/open/steamframe-desktop-first.md. Adds the only
configuration ever verified on a Steam Frame (y0usaf/steam-frame-nixos)
as an input whose nixpkgs is deliberately not followed, plus two
throwaway aarch64 probes: a plain lyte.shell + lyte.desktop system, and
the same with that device layer applied.

Both evaluate against our nixpkgs-unstable (26.11.20261014.319e4ce), so
the nixpkgs question is answered at evaluation: the device module takes
our pkgs, and its kernel is cross-compiled from our pkgs.path rather than
built natively on the Frame. The kernel and the two Frame-side packages
(frametop-nix, steam-aarch64-nix) are being built.

Four integration points the probe found, all of which a real host module
has to answer:

- The device layer hardcodes users.users.steamos at uid 1000, and so does
  default-module.nix, so the primary user has to be named "steamos" for
  the two definitions to merge instead of colliding on the uid. That is
  also the name Valve's session scripts, frametop and powerbuttond assume.
- default-module.nix declared users.groups.daniel literally. Any host
  that renamed lyte.username would have failed the primary-group
  assertion; it now follows the option.
- lyte.desktop.enable turns on systemd-boot, and lyte.bootloader.limine
  defaults to it, while the device layer owns installBootLoader through
  boot.loader.external. Both have to be off: there is no ESP to install
  to, and the boot files are written into slot A's filesystem.
- Nothing else in the desktop layer objected to aarch64 at evaluation.
lytedev force-pushed propose/steamframe-phase0 from 6c85f7e10c
Some checks failed
/ check-format (push) Successful in 18s
/ build (push) Failing after 2m20s
to bb8491c7c8
Some checks failed
/ check-format (push) Successful in 18s
/ build (push) Failing after 2m25s
2026-11-02 14:05:10 -06:00
Compare
feat(steamframe): put phases 1 and 2 in code as well as phase 3
All checks were successful
/ check-format (push) Successful in 17s
/ build (push) Successful in 1h35m47s
f1f7196ee0
The hardware-bound part of this was never as large as it looked: the
scripts, the image and the host config can all exist and be checked
before a Frame is in hand, and only running them needs the device.

Slot A is ours now, not the spike's. steamframeSlotA builds our own
closure as the slot-A btrfs filesystem -- Image, initrd.uImage, the DTBs
and the store, formatted with the UUID the config boots by -- reusing the
device layer's recipe for the parts a mistake cannot be seen without
hardware. The boot files and disk layout stay Valve's; the system inside
is ours. That also drops the dependency on their USB image, whose ESP and
efi-A files come from Valve's recovery image and are gitignored upstream.

write-slot-a.sh streams that filesystem to an idle rootfs-A over SSH and
verifies the checksum on the device, having first refused to run unless
the Frame is booted from slot B, the partition is labelled rootfs-A, and
it is not mounted. It requires the Wi-Fi .nmconnection to be baked in:
the Frame has no wired network, and a first boot with no network is
unreachable except through the recovery image. The read-only flag is
restored on exit, including on failure.

bootstrap-stock-steamos.sh is phase 1's code: the password sudo needs,
/etc/tmpfiles.d before the installer expects it, steam-deck mode so /nix
lives at /home/nix and survives updates, read-only back on, and the root
key the writer uses.

frame.storage.slotAUuid is no longer a placeholder read off the unit. We
choose it, because we format the filesystem: 9f6a2c1d-4b7e-4c2f-9d2a-
6f1b8c3e5a70. Nothing about that depends on hardware.

The first full toplevel build also found a real aarch64 failure: herdr
would not link, because libghostty-vt's zig-produced compiler_rt.o has
.debug_loc entries whose symbols are gone and ld.bfd refuses them. The
overlay selects lld for aarch64, where it links. That build is still
running as this commit is written; the fix is not yet proven end to end.

The issue records all of this, and stops calling phases 1 and 2 blocked.
fix(overlays): skip notmuch tests on aarch64, which time out under qemu
All checks were successful
/ check-format (push) Successful in 22s
/ build (push) Successful in 20m11s
02778b97fe
The Frame's toplevel build got past herdr and then failed in notmuch-0.40:
13 tests failed to report results, the first with exit 124. That is the
harness's per-test timeout expiring under emulation, not a failing
assertion -- the suite shells out to the notmuch binary it just built,
and qemu makes it far slower than the budget. The tests stay on for
every other platform.
fix(steamframe): slot A holds the recovery system; the pool holds ours
All checks were successful
/ check-format (push) Successful in 21s
/ build (push) Successful in 21m23s
f07e4017f5
The first slot-A build failed its own size check, and the numbers settle
the design. Our closure is 11.9 GiB with lyte.shell and 8.8 GiB without,
and the smaller one still needs 12.9 GiB of btrfs on disk because every
file costs a 4 KiB node; slot A is 10 GiB and is Valve's layout to grow,
not ours.

So slot A carries the device layer's recovery build -- Wi-Fi, root ssh,
the migration tools -- extended with our keys and our slot-A UUID, and
the long-lived system belongs in the btrfs pool on /dev/sda8, which is
also where slot A's /boot comes from: slot A mounts at /mnt/frame-boot
and /boot binds it, so the pool's kernel and initrd stay where U-Boot
looks. That is the device layer's design, arrived at from the other
direction.

rootfs.nix now builds the recovery root filesystem, so it brings in a
_second_ kernel build from the recovery config; that is building as this
is written. Creating the pool and installing the first generation into it
is destructive to SteamOS's home partition and needs the device, so it
stays unscripted and unnamed as arrival work rather than guessed at
here.
feat(steamframe): root the Frame on the pool, and script its creation
Some checks failed
/ check-format (push) Successful in 20s
/ build (push) Has been cancelled
76c860d7e6
Keeping lyte.shell settles where root lives. The shell is not what made
slot A infeasible -- 11.9 GiB is comfortable on the pool -- and nothing
in it had to be turned off: the full toplevel, shell included, builds for
aarch64. The two aarch64 problems were herdr's linker and the
notmuch/aerc suites under emulation, both handled in the overlay.

So frame.storage.poolUuid is set rather than null, chosen here for the
same reason slotAUuid is: the pool is formatted with that UUID, so
mkfs.btrfs -U and the config have to agree. The host now mounts @root,
@nix, @home, @games and @var from the pool, and slot A at /mnt/frame-boot
with /boot bound to it, which is how the pool's kernel and initrd stay
where Valve's U-Boot reads them.

create-pool.sh formats /dev/sda8 and creates the six subvolumes. It takes
CONFIRM_DESTROY=<device path> rather than a yes/no, because that partition
is SteamOS's home and Steam's library until it runs. Installing the first
generation into the pool stays manual: nix copy plus nixos-install --root
--no-bootloader, with a human watching the first time.
docs(steamframe): record the recovery filesystem's measured size
All checks were successful
/ check-format (push) Successful in 17s
/ build (push) Successful in 19m43s
536191f53b
2.4 GB of the 10 GiB slot, so slot A can hold the recovery profile,
the independent slot-A system profile and the boot files with room to
spare. Measured, not estimated: btrfs total_bytes from the built image.
Probing the first unit (SteamOS build 20261022.6150929) found three
ways the phase-1 bootstrap could not have run as written:

- steamos-readonly needs root; unprivileged, even `status` fails with
  "must be superuser to use mount". Both calls now go through sudo.
- `sudo -n true` fails for a set-but-uncached password as well as for
  none, so the old check re-ran passwd on every unit. passwd -S reports
  P/NP/L without privileges.
- Piping the script into `ssh ... bash -s` leaves sudo and passwd no
  terminal. The usage is now scp plus `ssh -t`.

Not run on the unit yet: the operator asked for a read-only probe, so
this is checked with bash -n and shellcheck only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
docs(steamframe): record the first hardware probe
Some checks failed
/ check-format (push) Has been cancelled
/ build (push) Has been cancelled
02d369d488
Read-only, as the unprivileged steamos user over ssh: rauc status and
config, the RAUC custom backend and post-install hook, kernelsetup.sh,
strings of splctl and of the shipped U-Boot image, modules.builtin,
power_supply/hwmon/mem_sleep, and the mounts on sda8. Nothing was
written and sudo was not used, so splctl get-primary and get-state
(which read the root-only bootenv) are still unanswered.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
docs(steamframe): compare the spike's pins with what the unit ships
Some checks failed
/ check-format (push) Has been cancelled
/ build (push) Has been cancelled
3ad1549e0a
pacman -Q and /proc/config.gz on the unit (build 20261022.6150929),
against the pins in y0usaf/steam-frame-nixos at f49bda99, with GitHub's
compare API on evlaV/deckard-linux and evlaV/deckard-mesa for which way
the revisions differ. Unprivileged, nothing written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
docs(steamframe): slot A can stay the default boot
Some checks failed
/ check-format (push) Has been cancelled
/ build (push) Has been cancelled
753641efac
Read /usr/bin/steamos-bootconf on the unit: the per-boot registration
only marks the booted slot good, and the primary moves only through
set-primary, which RAUC calls on update. Unprivileged, nothing written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
docs(steamframe): record the boot state the unit arrived with
All checks were successful
/ check-format (push) Successful in 20s
/ build (push) Successful in 25m31s
ca9b2e53b8
Root over ssh now that the operator installed a key, still read-only:
steamos-bootconf dump-config, the raw bootenv/bootenvb strings, the ESP
and efi-A contents, rootfs-A mounted ro,rescue=nologreplay, and
sha256 of uboot_*/ubootfw_*/ubootenv_* partitions against the images in
each slot's /boot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
feat(steamframe): a VR desktop: frametop's Plasma screens on NixOS
Some checks failed
/ check-format (push) Has been cancelled
/ build (push) Has been cancelled
f3a41df298
Ports frametop-nix's Home Manager module to a NixOS module,
lyte.steamframe.vrDesktop, and enables it on the steamframe host. This
flake carries no Home Manager, and on NixOS the root-side pieces
steamos-etc exists for (GPU drivers in /run/opengl-driver, uinput) are
ordinary options.

The shape follows the two Mesas the Frame already runs: the device
layer keeps Steam and SteamVR on Valve's Mesa inside its FHS, and
Plasma, KWin and ft-screens use nixpkgs' Mesa through
hardware.graphics, as frametop users on stock SteamOS run ft-screens
today. Steam launches the Desktop entry inside the FHS with Valve's
Mesa selected by FHS /usr paths, so the entry runs a wrapper that drops
those variables and sources /etc/set-environment before frametop's
session nests Plasma.

Ported: the input relay, 3D mouse, keyboard and power services, the
ft_pointer driver (same ~/.local/share path as the HM module, so
SteamVR's registration never moves), the menu entries, the
frametop.conf seed and migration, and the layout launchers. Left out:
gaze and hand tracking (root services with file capabilities; add when
wanted), and "Native Desktop" (there is no stock desktop here).

Differences from the HM module: the driver is registered by editing
openvrpaths.vrpath with jq before SteamVR starts rather than with
vrpathreg at activation, since vrpathreg only exists inside the FHS;
on a profile SteamVR has never started, the driver registers on the
second start. power-profiles-daemon, which Plasma enables, is turned
back off: the stock Frame ships none and leaves power to
steamos-manager.

Verified: the steamframe toplevel evaluates, with no display manager,
and the frametop units and home links are generated. NOT verified on
the hardware: the Frame is not flashed, and nothing here has run on it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
docs(steamframe): the host's desktop is the VR one, with its own gate
Some checks failed
/ check-format (push) Has been cancelled
/ build (push) Has been cancelled
8cfebe1351
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
feat(steamframe): the host on a USB stick, booted without touching either slot
Some checks failed
/ check-format (push) Has been cancelled
/ build (push) Has been cancelled
cad2cea2f6
A stick variant of the steamframe host (flake output steamframeUsbStick)
and a writer for it, so the VR desktop can be tried on the Frame before
anything is written to slot A. Valve's U-Boot has a "Boot from USB"
entry and a SteamOS (USB Boot) target (strings of the shipped U-Boot,
recorded in the issue), and the device layer already builds a USB image
in Valve's recovery-stick layout, which is the shape followed here.

Differences from the device layer's image.nix, all because the stick
is a guest on a Frame whose own storage must stay as it was:

- root on its own filesystem UUID, not slotAUuid, so a stick left
  plugged in after slot A is written cannot give the initrd two roots;
- frame-slot-good off: it writes Valve's boot environment, and its
  rauc.slot=A condition depends on what U-Boot passes for USB, which is
  unknown;
- /mnt/steamos-data and /home/steamos noauto: they mount the internal
  home partition, the one the device layer leaves writable;
- no var-A or home partition on the stick: nothing reads var-A, and a
  second "home" partlabel would make by-partlabel/home ambiguous;
- a 24 GiB root instead of 10, since our closure is 11.9 GiB;
- empty esp and efi-A; Valve's esp assets are copied on at write time
  from a local copy rather than entering the store or the repo.

Verified: the stick system evaluates with those overrides in effect;
the writer passes shellcheck, and its image-size parse was checked
against a real zstd frame. Not verified: the image has not finished
building, and whether U-Boot boots this layout from USB at all is
untested.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
fix(steamframe): let the VR desktop's logout watcher find NixOS's KWin
Some checks failed
/ check-format (push) Has been cancelled
/ build (push) Has been cancelled
3bb4eb6548
frametop's session ends a KWin that outlives Plasma's logout by
matching /usr/bin/kwin_wayland_wrapper in pgrep -f. NixOS' KWin runs
from the system profile, and its wrapper keeps that argv[0], so the
pattern never matched and a logout could leave the session up. Found by
grepping the built tree for the /usr paths left after the first patch.

Also records in the issue that the unit updated itself twice since the
probe, now runs Linux 7.2, and still has U-Boot's USB boot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
fix(steamframe): pin the FEX guest Mesa to the build Valve still lists
Some checks failed
/ check-format (push) Has been cancelled
/ build (push) Has been cancelled
af6f912875
The image build failed on a hash mismatch in the device layer's fetch
of deckard-mesa-linux-x86_64-26.3.0_devel+gite07916b4-5: same file name
and version, different bytes. The file on Valve's hotfix repository
was rebuilt in place on 2026-11-02 (.PKGINFO builddate 1793657766,
packager "Unknown Packager"), after the spike pinned it on 10-28, and
the spike's current head still carries the old hash.

Valve signs neither these packages nor the repository database
(SigLevel = Optional DatabaseOptional on the unit, and no .sig exists),
so the rebuilt file cannot be verified and was not adopted. The
repository database no longer lists gite07916b4-5 at all; it lists
git6a15f899-6 with a SHA-256, which is also exactly the version the
unit itself has installed (pacman -Q on SteamOS 0.5.8). That is the
pin now, with the database's checksum. The other two packages in the
FEX guest root still match the database byte for byte, so they stay.

The fix is a patch applied to the spike's source in lib/host.nix,
not an override: every spike module callPackages pkgs/valve.nix
itself, so there is no option to set. This is the "vendor the pins"
decision from issues/open/steamframe-desktop-first.md taking its first
concrete form.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
fix(steamframe): make the stick image's staging copy removable
Some checks failed
/ check-format (push) Has been cancelled
/ build (push) Has been cancelled
c71433b33e
cp -a keeps the store's read-only permissions, so the rm -rf that frees
the staged root after mkfs failed on every directory and failed the
build. Found by the first full image build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
fix(steamframe): keep the stick image script at one indentation
Some checks failed
/ check-format (push) Has been cancelled
/ build (push) Has been cancelled
39f34edce8
The previous fix's rm line landed four spaces short of the rest of
the build script, so Nix stripped less common indentation and the
partition table's heredoc terminator stayed indented; sfdisk then read
the rest of the script as partition commands ("line 7: unsupported
command"). Checked in the derivation that EOF now starts its line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
fix(steamframe): size the stick's root to the stick, and refuse an overflow
Some checks failed
/ check-format (push) Successful in 33s
/ build (push) Failing after 12m17s
e18fe40a6b
The first image that built had a 26.4 GB btrfs in a 24 GiB rootfs-A:
mkfs.btrfs --rootdir grows the file past its truncated size when the
content needs it, and with Plasma and frametop the system uses 18.4 GB
on disk. Nothing caught it because I had dropped the size check the
device layer's image.nix carries.

rootfs-A now fills the 31 457 280 000-byte stick on sanctuary-av, and
the build fails if the filesystem or its file is larger than the
partition. A different stick means changing targetStickBytes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjnZHBEqJWNXTTHBVEhMAK
Some checks failed
/ check-format (push) Successful in 33s
Required
Details
/ build (push) Failing after 12m17s
Required
Details
This pull request has changes conflicting with the target branch.
  • flake.lock
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin propose/steamframe-phase0:propose/steamframe-phase0
git switch propose/steamframe-phase0
Sign in to join this conversation.
No reviewers
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
lytedev/nix!1650
No description provided.