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

Runbook: WSL Bring-Up

Status: living

Use this when the target environment is the wsl host, running inside an existing nix-community/NixOS-WSL distro.

This is separate from the bare-metal install and first-bring-up flow because the commands, platform assumptions, and validation steps are materially different.

This runbook assumes you are already using the community WSL base:

The dubnium .#wsl target layers on top of that base. It is not a replacement for the initial NixOS-WSL installation process.

When To Use This

Use this runbook when:

  • you are already inside the NixOS WSL distro
  • you want to switch that distro to dubnium’s .#wsl target
  • you want to validate shared Dubnium wiring in WSL before touching the bare-metal workstation target

Do not use this runbook for:

  • bare-metal install
  • hosts/workstation/hardware-configuration.nix generation
  • EFI or bootloader validation
  • Hyprland or audio/studio validation

Preconditions

  • WSL is installed on Windows
  • a NixOS WSL distro based on nix-community/NixOS-WSL already exists and boots successfully
  • this repo is available inside the distro. Examples:
/mnt/c/Users/<user>/Projects/dubnium
~/src/dubnium
  • flakes are available, either through system config or explicit flags

Success Criteria

  • nixos-rebuild switch --flake .#wsl succeeds inside the WSL distro
  • git is available from the switched system generation
  • mode status, mode current, and mode desired work
  • dubnium.k3s.enable and dubnium.vllm.enable evaluate to false
  • compute.target evaluates without pulling in k3s or vllm.service
  • the runtime state directory exists at /run/mode-controller

1. Enter The NixOS WSL Distro

If you do not already have a working nix-community/NixOS-WSL distro, stop here and install that first. This runbook starts after that base is already in place.

Enter the distro:

wsl -d NixOS

Inside the distro, go to the repo:

cd /path/to/dubnium
pwd
git status --short

Use the actual checkout path for the machine. Avoid hardcoding personal paths in reusable docs or scripts.

2. Evaluate The WSL Target

If your shell does not already have flakes enabled, use explicit flags:

nix --extra-experimental-features "nix-command flakes" flake show .

Confirm the new target exists:

  • nixosConfigurations.wsl

Optional targeted checks:

nix --extra-experimental-features "nix-command flakes" eval .#nixosConfigurations.wsl.config.wsl.enable
nix --extra-experimental-features "nix-command flakes" eval .#nixosConfigurations.wsl.config.dubnium.boot.defaultMode
nix --extra-experimental-features "nix-command flakes" eval .#nixosConfigurations.wsl.config.dubnium.k3s.enable
nix --extra-experimental-features "nix-command flakes" eval .#nixosConfigurations.wsl.config.dubnium.vllm.enable
nix --extra-experimental-features "nix-command flakes" eval .#nixosConfigurations.wsl.config.systemd.targets.compute.wants

Expected:

  • wsl.enable = true
  • default mode is compute
  • dubnium.k3s.enable = false
  • dubnium.vllm.enable = false
  • compute.target has no vllm.service dependency

This confirms the dubnium host is using the upstream community WSL module, not an ad hoc local WSL implementation.

3. Switch The Running Distro To .#wsl

Use:

sudo nixos-rebuild switch --flake .#wsl

If flakes are not enabled globally in the current shell:

sudo nixos-rebuild switch --extra-experimental-features "nix-command flakes" --flake .#wsl

This is the main WSL install/activation command.

Keep config truth and live runtime truth separate. A targeted nix eval proves the flake expression, while nixos-rebuild switch and systemctl prove the running distro. If a full switch fails with an environmental WSL error, record that separately from whether the flake evaluated correctly.

4. Verify Dubnium Runtime Basics

Check mode/runtime state:

mode status
mode current
mode desired
sudo ls -la /run/mode-controller

Check that the heavy services are not part of the lightweight WSL profile:

systemctl status k3s --no-pager
systemctl status vllm --no-pager

Both units should be absent or inactive in the default WSL target. Enable them intentionally in a local override only when the task is specifically to validate their WSL runtime behavior.

Check the WSL target’s current interpretation:

  • wsl is headless
  • compute is the default desired mode
  • k3s and vllm are disabled by default to keep WSL activation lightweight
  • workstation-only graphics/audio expectations do not apply here

5. Known Differences From workstation

Important differences:

  • .#wsl assumes the distro itself was originally created with nix-community/NixOS-WSL
  • do not run nixos-generate-config --dir ./hosts/workstation for WSL testing
  • do not expect .#workstation to build cleanly until a real bare-metal hardware config has replaced the placeholder
  • do not use the fresh-install checklist for WSL bring-up
  • do not treat WSL results as proof of EFI, bootloader, Hyprland, or audio correctness

The wsl target is for:

  • flake composition
  • lightweight activation
  • shared Dubnium control-plane behavior

6. Common Failure Buckets

  • flakes not enabled in the current shell
  • repo is present but the running system has not been switched to .#wsl
  • Windows PATH injection adds noisy warnings during WSL startup
  • if repo tooling looks missing after switch, check git --version
  • Home Manager activation can fail if the active WSL login user does not match the configured Home Manager home; check whoami, getent passwd, and /etc/wsl.conf before changing modules
  • mode desired/current state is seeded but not yet reconciled automatically at boot

If .#workstation fails during WSL development, first check whether the failure comes from the placeholder hosts/workstation/hardware-configuration.nix instead of the new wsl target.