Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0007: WSL Is a Headless Validation Target

Status: accepted

Context

Dubnium needs a fast way to validate shared flake composition, module wiring, and mode-controller behavior before every change has to run on the bare-metal workstation target.

WSL is useful for that loop, but it is not equivalent to the real workstation. It does not validate EFI, bootloader behavior, workstation hardware generation, Hyprland, audio/studio behavior, NVIDIA runtime details, or final GPU topology.

The upstream nix-community/NixOS-WSL project already owns the WSL-specific boot and integration layer. Reimplementing that locally would create another platform surface for Dubnium to maintain before there is evidence that it is needed.

Decision

Keep wsl as a first-class flake host target for headless validation, built on top of nix-community/NixOS-WSL.

Use .#wsl to validate shared Dubnium composition and headless services inside an existing NixOS-WSL distro. Set its default Dubnium mode to compute, enable the shared mode controller, and keep resource-heavy services such as vllm and k3s disabled by default. Enable those services intentionally when the task is specifically to validate their WSL runtime behavior.

Do not treat .#wsl as a replacement for .#workstation, the bare-metal install path, or workstation hardware validation.

Consequences

  • Shared module wiring and activation can be exercised from a faster Windows/WSL loop.
  • WSL-specific platform support stays delegated to the upstream NixOS-WSL module.
  • The WSL target remains intentionally headless, compute-biased, and lightweight.
  • Passing WSL validation does not prove workstation graphics, audio, bootloader, EFI, NVIDIA, or final GPU behavior.
  • WSL runbooks and checks must stay separate from bare-metal first-bring-up and fresh-install procedures.

Escalation Criteria

Reconsider the WSL target shape if:

  • upstream NixOS-WSL no longer supports the required system integration points
  • WSL behavior diverges enough from Dubnium’s shared module graph to make the target misleading
  • bare-metal validation becomes cheap and reliable enough that a separate WSL target no longer reduces risk or cycle time