Setting up a Windows minion (previous version)
Install @geekbeer/minion on a Windows PC and that PC can work as a minion (self-hosted). You need administrator rights only for the initial setup and a couple of commands; day-to-day operation works from a regular user account.
What you need
Section titled “What you need”- A Windows PC dedicated to the minion
- An administrator account — for installing the package and running setup
- A user account for the minion — the minion keeps its data in this user’s folder (
%USERPROFILE%\.minion\). It can be the same account as the administrator - Node.js 22 LTS or later (22.23.4 / 24.22.1 or later) — setup does not install Node.js. Install it from nodejs.org first. Older versions have a bug in Brotli decompression (CVE-2026-111497) that can let a malicious server run code on the minion. If yours is older, install a newer one over it and run
minion-cli-win restart - WSL (optional) — if you want WSL terminals, install WSL before running setup
If PowerShell’s execution policy is still the default Restricted, npm won’t run. Allow scripts first with one of these:
# Allow for the current user (recommended)Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
# Allow for this PowerShell window onlySet-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSignedRemoteSigned runs local scripts and requires a signature on scripts downloaded from the internet. If you run npm from Command Prompt (cmd.exe) instead of PowerShell, you don’t need this.
1. Register the minion in HQ
Section titled “1. Register the minion in HQ”Open Minions in the sidebar, click Add Minion, choose Self-host VPS and press Register Minion. (Its description mentions Ubuntu/Debian, but it is also the option for Windows.)
HQ then shows the commands to run. Choose Windows and copy them. You can find the same commands later under Setup Command on the minion’s page.
2. Install the package (administrator PowerShell)
Section titled “2. Install the package (administrator PowerShell)”npm install -g @geekbeer/minionWhen it finishes, open a new administrator PowerShell window so the new minion-cli-win command is picked up.
3. Run setup (administrator PowerShell)
Section titled “3. Run setup (administrator PowerShell)”minion-cli-win setupSetup asks you to confirm — type yes. If the PC has more than one user, choose by number which user becomes the minion.
Setup then does the following (it takes a few minutes):
- Installs Git and Claude Code
- Registers the minion as a Windows service
- Registers screen sharing (TightVNC) to start when the minion’s user signs in — and, if WSL is installed, WSL terminals too
- Installs the piece that relays screen sharing to HQ (websockify), installing Python from python.org if it is missing
- Installs Cloudflare Tunnel (cloudflared), which HQ uses to reach the minion
- Turns off the screensaver, the lock on resume, sleep and the display timeout
- Adds inbound firewall rules
4. Connect to HQ (the minion user’s PowerShell)
Section titled “4. Connect to HQ (the minion user’s PowerShell)”Sign in as the minion’s user and, in a PowerShell window that is not elevated, run the second half of the commands HQ showed you (configure):
minion-cli-win configure ` --hq-url https://<your HQ URL> ` --minion-id <minion ID> ` --api-token <API token> ` --setup-tunnelKeep --setup-tunnel. HQ reaches the minion through this tunnel; without it, the terminal, screen and files won’t work from HQ. The commands HQ shows include it.
configure saves the connection details, starts the minion and screen sharing, and tells HQ the minion is connected.
5. Sign in to the AI
Section titled “5. Sign in to the AI”A minion needs an AI model (LLM) it can use before it can do any work. From the minion’s page in HQ, open screen sharing (VNC) to the PC, run claude in PowerShell and sign in. To use a different AI, see LLM Plugins.
6. Check that it works
Section titled “6. Check that it works”The minion shows as online on the Minions page. You can also check on the PC:
minion-cli-win status # the minion's statusminion-cli-win health # health checkKeep it running after a restart
Section titled “Keep it running after a restart”Screen sharing and WSL terminals run only while the minion’s user is signed in. So that they come back after the PC restarts, set Windows to sign in to the minion’s user automatically. If the PC will run without a display, also see Running without a display.
Day-to-day commands
Section titled “Day-to-day commands”minion-cli-win status # the minion's statusminion-cli-win health # health checkminion-cli-win daemons # state of the services and screen sharingminion-cli-win diagnose # detailed diagnosisminion-cli-win restart # restart the minionminion-cli-win stop # stop the minionminion-cli-win start # start the minionminion-cli-win version # versionTwo commands need an administrator PowerShell:
minion-cli-win restart --all # restart every service and screen sharingminion-cli-win stop --force # force-stop when a normal stop doesn't workrestart --all— use it when the minion stays offline after a restart or a Windows Update. Plainrestartrestarts only the minion itself, so it doesn’t help when the connection to HQ (cloudflared) is downstop --force— use it whenstopdoesn’t work, for example after a failed update. Work in progress is interrupted. See Windows minion will not stop for details
Logs are in the minion user’s %USERPROFILE%\.minion\logs\.
Get-Content $env:USERPROFILE\.minion\logs\service-stdout.log -Tail 50Get-Content $env:USERPROFILE\.minion\logs\service-stderr.log -Tail 50Get-Content $env:USERPROFILE\.minion\logs\cloudflared-stderr.log -Tail 50 # connection to HQUpdating
Section titled “Updating”When the minion’s page in HQ shows Update to v…, press it to update. If the minion doesn’t start after an update, see Troubleshooting.
Reconnecting
Section titled “Reconnecting”If you recreate the connection details with Re-register in HQ, run configure again with the command it shows. If that command has no --setup-tunnel, add it.
Uninstalling
Section titled “Uninstalling”Run these in an administrator PowerShell:
minion-cli-win uninstall # remove the minion (--keep-data keeps the connection details)npm uninstall -g @geekbeer/minion # remove the packageNode.js, Claude Code, TightVNC, Git, Python and cloudflared stay installed. Remove them from Windows’ Apps settings if you no longer need them.
Running without a display
Section titled “Running without a display”When a mini PC runs without a display, screen sharing has no screen to show, and HQ’s screen sharing goes black.
Plug an HDMI dummy plug (headless display adapter) into the HDMI port. Windows then sees a display, and screen sharing works. They are inexpensive, and nothing needs to be configured.
When the screen looks small
Section titled “When the screen looks small”With a dummy plug, the shared screen can appear shrunk to about a quarter of its size (clicks still land where they would on the full-size screen).
Many inexpensive dummy plugs report a high resolution such as 4K, so Windows raises display scaling to 150–200%. With some plugs, the resolution goes back to 4K on reconnect even if you set 1920x1080.
Fix 1: set display scaling to 100% (recommended) — on a PC dedicated to the minion, readability doesn’t matter. Set Settings → Display → Scale & layout to 100%, then sign out and back in (or restart).
# Check the current setting (96=100%, 120=125%, 144=150%, 192=200%)Get-ItemProperty 'HKCU:\Control Panel\Desktop\WindowMetrics' -Name AppliedDPIFix 2: run TightVNC without display scaling
$tvnPath = 'C:\Program Files\TightVNC\tvnserver.exe'if (-not (Test-Path $tvnPath)) { $tvnPath = "$env:USERPROFILE\.minion\tightvnc\PFiles\TightVNC\tvnserver.exe" }New-Item -Path "HKCU:\Software\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\Layers" -ForceSet-ItemProperty -Path "HKCU:\Software\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\Layers" ` -Name $tvnPath -Value "~ DPIUNAWARE"Then restart screen sharing from an administrator PowerShell:
Stop-Process -Name tvnserver -Force -ErrorAction SilentlyContinueschtasks /Run /TN MinionVNCFix 3: use a dummy plug whose resolution you can change — a plug with a rewritable EDID (such as Headless Ghost) can be fixed at 1920x1080 or another resolution. They cost more.
Troubleshooting
Section titled “Troubleshooting”npm fails because running scripts is disabled
Section titled “npm fails because running scripts is disabled”npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system.PowerShell’s execution policy is still Restricted. Allow scripts as described in What you need, or run the command from Command Prompt (cmd.exe).
minion-cli-win is not found
Section titled “minion-cli-win is not found”minion-cli-win : The term 'minion-cli-win' is not recognized as the name of a cmdlet, function, script file, or operable program.Open a new PowerShell window after npm install -g. If the minion’s user can’t find it, sign out and back in. If it still isn’t found, add npm’s command folder to PATH and open a new window:
[Environment]::SetEnvironmentVariable('PATH', [Environment]::GetEnvironmentVariable('PATH', 'User') + ';' + (npm prefix -g), 'User')The terminal component (node-pty) fails to install
Section titled “The terminal component (node-pty) fails to install”Setup installs the terminal component into the package’s own folder. If that failed, install it there again from an administrator PowerShell:
Set-Location "$(npm prefix -g)\node_modules\@geekbeer\minion"npm install node-pty-prebuilt-multiarchIf that also fails, install Visual Studio Build Tools and run npm install node-pty.
npm install -g shows a better-sqlite3 build error
Section titled “npm install -g shows a better-sqlite3 build error”You can ignore it. better-sqlite3 is optional and the install has succeeded; the minion uses the database built into Node.js instead.
The minion doesn’t start
Section titled “The minion doesn’t start”Find the cause with the diagnostic commands and the logs:
minion-cli-win diagnoseminion-cli-win daemonsThe minion doesn’t start after an update
Section titled “The minion doesn’t start after an update”If it fails with an error like Error: Cannot find module './refs/data.json', some files weren’t replaced during the update. Stop it and reinstall from an administrator PowerShell:
minion-cli-win stop --forcenpm install -g @geekbeer/minion@latestminion-cli-win restart --allIf stop --force doesn’t work either, stop it with the steps in Windows minion will not stop. The update log is %USERPROFILE%\.minion\logs\update-agent.log.
The minion stays offline after a restart
Section titled “The minion stays offline after a restart”- Run
minion-cli-win restart --allin an administrator PowerShell - Check that the minion’s user is signed in (see Keep it running after a restart)
- If it still doesn’t come back, read the log of the connection to HQ (
cloudflared-stderr.log). If%USERPROFILE%\.cloudflared\config.ymldoesn’t exist, runconfigureagain with--setup-tunnel
Screen sharing (VNC) doesn’t connect
Section titled “Screen sharing (VNC) doesn’t connect”“Server is not configured properly” — check TightVNC’s settings, both for the minion’s user (HKCU) and for the whole PC (HKLM):
foreach ($root in 'HKCU', 'HKLM') { Get-ItemProperty "${root}:\Software\TightVNC\Server" -ErrorAction SilentlyContinue | Select-Object PSPath, UseVncAuthentication, LoopbackOnly, AllowLoopback}The expected values are UseVncAuthentication=0, LoopbackOnly=1 and AllowLoopback=1. If they differ, run minion-cli-win setup again from an administrator PowerShell, then restart screen sharing:
Stop-Process -Name tvnserver -Force -ErrorAction SilentlyContinueschtasks /Run /TN MinionVNCThe relay (websockify) isn’t running — Python was probably missing. Install Python, then run minion-cli-win setup again from an administrator PowerShell:
winget install Python.Python.3.12Check the ports
netstat -an | Select-String "5900" # TightVNCnetstat -an | Select-String "6080" # websockify