Skip to content
AndonDocs
GitHub
Run machines and deploy / Machines

Windows machines

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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

  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:

    shell
    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), 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 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), 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:

    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'
  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 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.

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.