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). 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
- Create a separate standard (not administrator) local account for the agent, say
andon. - 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
-
Install Tailscale for Windows, sign in, and turn on Run unattended in its preferences, so it stays connected when nobody is signed in.
-
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.0Set-Service sshd -StartupType Automatic; Start-Service sshdSet-NetFirewallRule -Name OpenSSH-Server-In-TCP -RemoteAddress 100.64.0.0/10 # only the tailnet -
Signed in as
andon, add your computer’s public key (one line):PowerShell New-Item -ItemType Directory -Force $env:USERPROFILE\.ssh | Out-NullSet-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
-
In the admin PowerShell, run
wsl --install --no-distribution, then restart the PC. -
wsl --install -d Ubuntu-24.04doesn’t work over SSH. Asandon, import Ubuntu’s own WSL image instead, which needs neither an admin nor a window. Check it against theSHA256SUMSfile athttps://cloud-images.ubuntu.com/wsl/releases/24.04/current/:PowerShell $d = "$env:USERPROFILE\wsl"; New-Item -ItemType Directory -Force $d | Out-Nullcurl.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 SHA256SUMSwsl --import Ubuntu "$d\ubuntu" "$d\ubuntu.rootfs.tar.gz" --version 2wsl --set-default Ubuntu -
Inside it, as root (
wsl -d Ubuntu -u root -- bash -s), add a Linux user, turn on systemd and make that user the default:shell useradd -m -s /bin/bash andonprintf '[boot]\nsystemd=true\n\n[user]\ndefault=andon\n' > /etc/wsl.conf -
On a PC someone else uses, cap what Linux may take. In the
andonaccount’s%USERPROFILE%\.wslconfig:INI [wsl2]memory=8GBprocessors=4Then run
wsl --shutdownso 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
-
As root, install git, tmux and ffmpeg from Ubuntu, gh from GitHub’s own apt repository (its install page), and turn on linger for the agent’s user:
shell 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 ghloginctl enable-linger andon -
As
andon, install Node 22 from nodejs.org into~/.local(the same commands as on a NAS: A NAS as a machine), then Claude Code withcurl -fsSL https://claude.ai/install.sh | bash. -
Run the installer as a systemd user unit, not straight from
wsl. WSL stops the processes awsl.execommand started when that command exits, so an installer left in tmux ornohupfrom an SSH session is gone when you look again.systemd-run --userkeeps it going and logs it:shell 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' -
Read
~/andon-install.logfor the/enrolllink and code, and approve the machine from your phone. -
Sign in gh and Claude Code the same way.
gh auth login --webruns as a unit and prints a device code.claude auth loginwants its code pasted back, so run it in tmux undersystemd-run --user --scopeand send the code withtmux send-keys -l. Finish withgh auth setup-git. -
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 registers a scheduled task, Andon WSL keep-alive,
that starts the distro at startup as the andon account and keeps it running.
-
Copy
keepalive.ps1from the Andon repository onto the PC, for example intoC:\Users\andon\. -
In an administrator, 64-bit PowerShell, in that folder, run:
PowerShell powershell -ExecutionPolicy Bypass -File keepalive.ps1 -User andon -Distro Ubuntu-Userand-Distrodefault toandonandUbuntu. The script asks for the account’s password, which the task runs with. -
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 addandon. Keep the groups that are already listed. -
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:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestartdism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestartwinget install --id Microsoft.WSL --source wingetdoes 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.
The board terminal won’t open on the PC. The board has no terminal helper for linux-x64. Runs still work. See
Agent updates.
The agent doesn’t update itself. No release key is pinned on the machine: Agent updates.
