Skip to content

Windows (WSL2)#

A Windows PC joins a cluster through WSL2, the Linux that ships with Windows. The agent runs inside your WSL distribution exactly as on a Linux machine, and runs use the GPU through the Windows NVIDIA driver: CUDA images, notebooks, development environments and agent runs all work. Use this page to add a PC, keep it up, and know its limits.

Before you begin#

  • Windows 11, or Windows 10 21H2 or newer, with WSL2 and a distribution installed (wsl --install -d Ubuntu in PowerShell).
  • For a GPU: an NVIDIA GPU with the Windows driver. Do not install a Linux NVIDIA driver inside WSL; nvidia-smi in your distribution should already list the GPU.
  • An account with sudo inside the distribution. Being an administrator on Windows helps for one step (starting WSL with Windows); the installer prints the command for an administrator when it is not.
  • Outbound HTTPS, as for any machine (Network and firewalls).

Add the PC#

  1. In the console, open Machines → Add machine and copy the install command.
  2. Open your distribution (for example Ubuntu from the Start menu) and paste the command.

  3. If systemd is off in the distribution, the installer asks to turn it on ([boot] systemd=true in /etc/wsl.conf) and stops. In PowerShell run:

    wsl --shutdown

    Reopen the distribution and run the same command again.

  4. The installer recognises the GPU through WSL2 and then offers three changes on the Windows side, each asked separately:

    Question What it changes Why
    Keep WSL's VM running when idle vmIdleTimeout=-1 under [wsl2] in your %USERPROFILE%\.wslconfig (a backup is kept) WSL stops its VM a little after the last terminal closes, and the machine goes Down.
    Start the distribution when Windows starts A scheduled task, Astralyx WSL, that runs wsl.exe -d <distro> -u root -- sleep infinity at startup The agent is back after a reboot, without anyone signing in. Needs an administrator: if Windows refuses, the installer prints the PowerShell command to run as administrator.
    Keep Windows from sleeping while plugged in powercfg /change standby-timeout-ac 0 A sleeping PC stops its runs.

    Each change prints how to undo it. --yes answers yes to all of them; --no-windows-setup leaves Windows as it is.

  5. The machine appears in Machines marked Windows (WSL2), with its GPU.

Check the GPU in a run#

astra astraeus run --name gpu-check --gpus 1 --wait \
  --image nvidia/cuda:12.6.0-base-ubuntu24.04 -- nvidia-smi

The log lists your GPU. When the workspace has other GPU machines, put the PC in a pool of its own and add --pool <pool> (Pools, labels and topology).

What differs from a Linux machine#

On WSL2
GPUs Given to a run as a whole: WSL exposes the GPUs together, so a run that asks for GPUs on a PC with two gets both (and its quota counts both). With one GPU, nothing changes.
GPU driver The Windows driver; the installer never installs a Linux one. Update it from Windows.
Uptime The PC must stay on and awake, and WSL running (the three steps above).
Resources WSL gets half of the PC's memory by default. Raise it with memory= under [wsl2] in .wslconfig, then wsl --shutdown.
Network Outbound only, as on Linux.

When the machine is Down#

The console says when a Windows machine is Down. Usually Windows is asleep, or WSL stopped the distribution. Check, in this order:

  1. The PC is on and awake.
  2. The distribution is running: wsl -l -v in PowerShell shows it Running. Start it with wsl -d <distro>.
  3. The agent is running inside it: systemctl status astraeus-agent.
  4. .wslconfig has vmIdleTimeout=-1, and the Astralyx WSL task exists (Get-ScheduledTask -TaskName 'Astralyx WSL').

Remove the PC#

Run the uninstall from your distribution, as for Linux (Update, drain and remove). It also offers to remove the Astralyx WSL task. The .wslconfig backup sits next to it if you want the old file back.