Skip to content

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.

  • 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:

Terminal window
# Allow for the current user (recommended)
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
# Allow for this PowerShell window only
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned

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

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)”
Terminal window
npm install -g @geekbeer/minion

When it finishes, open a new administrator PowerShell window so the new minion-cli-win command is picked up.

Terminal window
minion-cli-win setup

Setup 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):

Terminal window
minion-cli-win configure `
--hq-url https://<your HQ URL> `
--minion-id <minion ID> `
--api-token <API token> `
--setup-tunnel

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

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.

The minion shows as online on the Minions page. You can also check on the PC:

Terminal window
minion-cli-win status # the minion's status
minion-cli-win health # health check

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.

Terminal window
minion-cli-win status # the minion's status
minion-cli-win health # health check
minion-cli-win daemons # state of the services and screen sharing
minion-cli-win diagnose # detailed diagnosis
minion-cli-win restart # restart the minion
minion-cli-win stop # stop the minion
minion-cli-win start # start the minion
minion-cli-win version # version

Two commands need an administrator PowerShell:

Terminal window
minion-cli-win restart --all # restart every service and screen sharing
minion-cli-win stop --force # force-stop when a normal stop doesn't work
  • restart --all — use it when the minion stays offline after a restart or a Windows Update. Plain restart restarts only the minion itself, so it doesn’t help when the connection to HQ (cloudflared) is down
  • stop --force — use it when stop doesn’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\.

Terminal window
Get-Content $env:USERPROFILE\.minion\logs\service-stdout.log -Tail 50
Get-Content $env:USERPROFILE\.minion\logs\service-stderr.log -Tail 50
Get-Content $env:USERPROFILE\.minion\logs\cloudflared-stderr.log -Tail 50 # connection to HQ

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.

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.

Run these in an administrator PowerShell:

Terminal window
minion-cli-win uninstall # remove the minion (--keep-data keeps the connection details)
npm uninstall -g @geekbeer/minion # remove the package

Node.js, Claude Code, TightVNC, Git, Python and cloudflared stay installed. Remove them from Windows’ Apps settings if you no longer need them.

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.

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

Terminal window
# Check the current setting (96=100%, 120=125%, 144=150%, 192=200%)
Get-ItemProperty 'HKCU:\Control Panel\Desktop\WindowMetrics' -Name AppliedDPI

Fix 2: run TightVNC without display scaling

Terminal window
$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" -Force
Set-ItemProperty -Path "HKCU:\Software\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\Layers" `
-Name $tvnPath -Value "~ DPIUNAWARE"

Then restart screen sharing from an administrator PowerShell:

Terminal window
Stop-Process -Name tvnserver -Force -ErrorAction SilentlyContinue
schtasks /Run /TN MinionVNC

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

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 : 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:

Terminal 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:

Terminal window
Set-Location "$(npm prefix -g)\node_modules\@geekbeer\minion"
npm install node-pty-prebuilt-multiarch

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

Find the cause with the diagnostic commands and the logs:

Terminal window
minion-cli-win diagnose
minion-cli-win daemons

The 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:

Terminal window
minion-cli-win stop --force
npm install -g @geekbeer/minion@latest
minion-cli-win restart --all

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

  1. Run minion-cli-win restart --all in an administrator PowerShell
  2. Check that the minion’s user is signed in (see Keep it running after a restart)
  3. If it still doesn’t come back, read the log of the connection to HQ (cloudflared-stderr.log). If %USERPROFILE%\.cloudflared\config.yml doesn’t exist, run configure again with --setup-tunnel

“Server is not configured properly” — check TightVNC’s settings, both for the minion’s user (HKCU) and for the whole PC (HKLM):

Terminal window
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:

Terminal window
Stop-Process -Name tvnserver -Force -ErrorAction SilentlyContinue
schtasks /Run /TN MinionVNC

The relay (websockify) isn’t running — Python was probably missing. Install Python, then run minion-cli-win setup again from an administrator PowerShell:

Terminal window
winget install Python.Python.3.12

Check the ports

Terminal window
netstat -an | Select-String "5900" # TightVNC
netstat -an | Select-String "6080" # websockify