# Windows machines

Cards run on macOS and Linux. The agent needs tmux, so it doesn't run on Windows itself. It runs in WSL2, Windows'
built-in Linux, as the ordinary Linux agent ([Linux machines](https://andon-docs.pages.dev/machines/linux.md)). This page sets up an always-on Windows PC
once, so that you can do the rest over SSH and the agent comes back after a reboot with nobody signed in to Windows.

Most steps need an **administrator, 64-bit** PowerShell. The rest run as the agent's own account.

## 1. Make a Windows account for the agent

1. Create a separate **standard** (not administrator) local account for the agent, say `andon`.
2. Sign in to it once, so Windows creates its profile.

Its WSL distro, the agent's config and credentials, the gh and Claude Code logins and the clones all live in that
profile, apart from whoever uses the PC. Keep it standard: Windows' OpenSSH reads an administrator's keys from
`C:\ProgramData\ssh\administrators_authorized_keys`, not from the account's own `.ssh` folder. This keeps the agent out of the everyday
user's way. Admins on the PC can still read its profile.

## 2. Turn on SSH over the tailnet

1. Install Tailscale for Windows, sign in, and turn on **Run unattended** in its preferences, so it stays connected
   when nobody is signed in.
2. In an admin PowerShell, install and start OpenSSH, and let only the tailnet reach it:

   ```powershell
   Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
   Set-Service sshd -StartupType Automatic; Start-Service sshd
   Set-NetFirewallRule -Name OpenSSH-Server-In-TCP -RemoteAddress 100.64.0.0/10   # only the tailnet
   ```

3. Signed in as `andon`, add your computer's public key (one line):

   ```powershell
   New-Item -ItemType Directory -Force $env:USERPROFILE\.ssh | Out-Null
   Set-Content $env:USERPROFILE\.ssh\authorized_keys '<your public key>'
   ```

Over SSH the shell is `cmd.exe`, which mangles quoting in long commands. Send Linux commands as a script on stdin
instead: `ssh andon@<pc> 'wsl -d Ubuntu -u andon -- bash -s' < script.sh`. WSL prints its own messages in UTF-16,
which shows up spaced out (`W S L   v e r s i o n`); pipe it through `tr -d '\0'`.

## 3. Install WSL and Ubuntu

1. In the admin PowerShell, run `wsl --install --no-distribution`, then restart the PC.
2. `wsl --install -d Ubuntu-24.04` doesn't work over SSH. As `andon`, import Ubuntu's own WSL image instead, which needs
   neither an admin nor a window. Check it against the `SHA256SUMS` file at
   `https://cloud-images.ubuntu.com/wsl/releases/24.04/current/`:

   ```powershell
   $d = "$env:USERPROFILE\wsl"; New-Item -ItemType Directory -Force $d | Out-Null
   curl.exe -fsSL -o "$d\ubuntu.rootfs.tar.gz" https://cloud-images.ubuntu.com/wsl/releases/24.04/current/ubuntu-noble-wsl-amd64-wsl.rootfs.tar.gz
   (Get-FileHash "$d\ubuntu.rootfs.tar.gz" -Algorithm SHA256).Hash.ToLower()   # compare with SHA256SUMS
   wsl --import Ubuntu "$d\ubuntu" "$d\ubuntu.rootfs.tar.gz" --version 2
   wsl --set-default Ubuntu
   ```

3. Inside it, as root (`wsl -d Ubuntu -u root -- bash -s`), add a Linux user, turn on systemd and make that user the
   default:

   ```sh
   useradd -m -s /bin/bash andon
   printf '[boot]\nsystemd=true\n\n[user]\ndefault=andon\n' > /etc/wsl.conf
   ```

4. On a PC someone else uses, cap what Linux may take. In the `andon` account's `%USERPROFILE%\.wslconfig`:

   ```ini
   [wsl2]
   memory=8GB
   processors=4
   ```

   Then run `wsl --shutdown` so it applies.

Networking needs nothing extra: with Tailscale on Windows, WSL's default network reaches the board's
`https://<machine>.<tailnet>.ts.net` address.

## 4. Install the tools and the agent

1. As root, install git, tmux and ffmpeg from Ubuntu, gh from GitHub's own apt repository
   ([its install page](https://github.com/cli/cli/blob/trunk/docs/install_linux.md)), and turn on linger for the
   agent's user:

   ```sh
   apt-get update && apt-get install -y git tmux curl ca-certificates xz-utils ffmpeg
   # gh: add GitHub's apt repository as its install page says, then:
   apt-get install -y gh
   loginctl enable-linger andon
   ```

2. As `andon`, install Node 22 from nodejs.org into `~/.local` (the same commands as on a NAS:
   [A NAS as a machine](https://andon-docs.pages.dev/machines/nas.md#install-the-tools-in-your-home-folder)), then Claude Code with
   `curl -fsSL https://claude.ai/install.sh | bash`.
3. Run the installer as a systemd user unit, not straight from `wsl`. WSL stops the processes a `wsl.exe` command
   started when that command exits, so an installer left in tmux or `nohup` from an SSH session is gone when you look
   again. `systemd-run --user` keeps it going and logs it:

   ```sh
   export XDG_RUNTIME_DIR=/run/user/$(id -u)
   systemd-run --user --unit=andon-install --setenv=PATH=$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin \
     --working-directory=$HOME bash -c \
     'curl -fsSL https://<your board>/install.sh | sh -s -- --yes --preset open --no-install-claude --no-browser > $HOME/andon-install.log 2>&1'
   ```

4. Read `~/andon-install.log` for the `/enroll` link and code, and approve the machine from your phone.
5. Sign in gh and Claude Code the same way. `gh auth login --web` runs as a unit and prints a device code.
   `claude auth login` wants its code pasted back, so run it in tmux under `systemd-run --user --scope` and send the
   code with `tmux send-keys -l`. Finish with `gh auth setup-git`.
6. On a shared PC, let the machine run one card at a time: open **Settings → Machines**, press **Edit** (the pencil) on
   the PC, and set **Max concurrent runs** to 1.

## 5. Keep it running from boot

Nothing starts WSL at boot, and without WSL the agent's service never runs. The script
[`deploy/wsl/keepalive.ps1`](https://github.com/psci-labs/andon/blob/main/deploy/wsl/keepalive.ps1) registers a scheduled task, **Andon WSL keep-alive**,
that starts the distro at startup as the `andon` account and keeps it running.

1. Copy `keepalive.ps1` from the Andon repository onto the PC, for example into `C:\Users\andon\`.
2. In an **administrator, 64-bit** PowerShell, in that folder, run:

   ```powershell
   powershell -ExecutionPolicy Bypass -File keepalive.ps1 -User andon -Distro Ubuntu
   ```

   `-User` and `-Distro` default to `andon` and `Ubuntu`. The script asks for the account's password, which the task
   runs with.
3. If it says the account **can't log on as a batch job**, grant that right and run the script again: open
   `secpol.msc`, go to **Local Policies → User Rights Assignment → Log on as a batch job**, and add `andon`. Keep the
   groups that are already listed.
4. Restart the PC, leave it at the sign-in screen, and look for the machine on the board. It should come back within a
   minute.

The `andon` account can't register the task itself: a startup task needs an administrator, and the `ScheduledTasks`
cmdlets fail over SSH with `Cannot connect to CIM server. Access denied`.

## Troubleshooting

**`Program 'wsl.exe' failed to run: The file cannot be accessed by the system`.** Turn the features on directly and
install WSL from winget, then restart:

```powershell
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
winget install --id Microsoft.WSL --source winget
```

**`does not support 32-bit Windows` on 64-bit Windows.** The window is the 32-bit PowerShell
(`[Environment]::Is64BitProcess` is `False`). Start the 64-bit one from it with
`C:\Windows\Sysnative\WindowsPowerShell\v1.0\powershell.exe`. `keepalive.ps1` refuses to run in the 32-bit one.

**`wsl --install -d …` fails over SSH** with `requires an interactive window station` (`Wsl/0x800705b3`). Import the
image as in step 3.

**SSH offers only old key exchanges** (`no matching key exchange method found. Their offer:
diffie-hellman-group1-sha1,…`). Another SSH server (freeSSHd, say) listens on port 22 too. Find it with
`Get-NetTCPConnection -LocalPort 22 -State Listen | % { Get-Process -Id $_.OwningProcess }`, then stop and disable
whatever isn't `sshd`, or move OpenSSH to another port (`Port 2222` in `C:\ProgramData\ssh\sshd_config`, plus a
firewall rule for it).

**SSH times out after a reboot while `sshd` runs.** It may be listening on IPv6 only (`[::]:22`, not `0.0.0.0:22`).
Check with `netstat -ano | findstr ":22 "`. `Restart-Service sshd` fixes it; if it comes back after each reboot, try
`Set-Service sshd -StartupType AutomaticDelayedStart`.

**The keep-alive task never starts.** `schtasks /query /v` shows last result `267011` (0x41303, *has not run*), and
with Task Scheduler history on (`wevtutil sl Microsoft-Windows-TaskScheduler/Operational /e:true`) the attempt fails
with `0x80070569` (*logon type not granted*). The account lacks **Log on as a batch job**: see step 3 of
[Keep it running from boot](#5-keep-it-running-from-boot).

**The board terminal won't open on the PC.** The board has no terminal helper for `linux-x64`. Runs still work. See
[Agent updates](https://andon-docs.pages.dev/machines/updates.md#the-terminal-helper).

**The agent doesn't update itself.** No release key is pinned on the machine: [Agent updates](https://andon-docs.pages.dev/machines/updates.md#pin-the-release-key).
