Windows and macOS wizards
On Windows, Spitfire runs on Docker Desktop or on Docker Engine inside WSL2; you install it with one PowerShell command or with the setup.exe / .msi wizard. For macOS there is a .dmg wizard for those who would rather skip the terminal. All of them run the same installer underneath, and the result is the same as installing with Docker. Docker Desktop does not run on Windows Server; use a Linux virtual machine there, while a remote runner does run on Windows Server as a service.
Installing on Windows
Run in PowerShell:
irm https://spitfire.sh/ps | iexWithout Docker Desktop it asks to install it (winget), when it is stopped it asks to start it; if you say no it stops and says what to do (No Docker or Kubernetes yet). The bundle is unpacked into
%USERPROFILE%\spitfire(change it with$env:SPITFIRE_DIR, pick a release with$env:SPITFIRE_VERSION).Success check: a green box shows
http://localhost:8470; the installation details are also written to%USERPROFILE%\spitfire\spitfire-install-info.txt.To pass options, call the installer as a scriptblock:
& ([scriptblock]::Create((irm https://spitfire.sh/ps))) docker -Port 8480 -GrpcPort 8481 -Runners 4
The install.ps1 options are those of install.sh in PowerShell spelling (--runners → -Runners): Installer options. Only -Wsl is Windows-specific (below). To install only a runner on a Windows server without Docker, use the command on the Windows tab of the key dialog on the Runners page: Runners.
Without Docker Desktop: Docker Engine inside WSL2
Docker Desktop needs a paid subscription in companies with more than 250 employees or more than $10 million in annual revenue; Docker Engine is Apache 2.0 licensed and free. Spitfire also runs on Docker Engine inside an Ubuntu-24.04 in WSL2. When Docker is missing the installer asks Docker is not installed. How shall we go on?; the second choice is this path.
Run in PowerShell (no administrator shell needed; Windows asks for approval once to turn on WSL2):
& ([scriptblock]::Create((irm https://spitfire.sh/ps))) docker -WslThe installer turns on WSL2 (
wsl --install --no-distribution), installsUbuntu-24.04(reusing an existing one without touching its files), installs Docker Engine in it from download.docker.com, installs Spitfire into/opt/spitfireand adds the Spitfire WSL scheduled task that starts WSL2 and Docker when you sign in.If it says
WSL2 is installed; Windows needs a restart before it can be used., restart the computer and run the command from step 1 again, unchanged; it goes on where it stopped.Success check: the green box shows
http://localhost:8470and this printsOK:if ((Invoke-WebRequest -UseBasicParsing http://localhost:8470/readyz).StatusCode -eq 204) { 'OK' }To check that it will come back after a restart:
Get-ScheduledTask -TaskName 'Spitfire WSL' | Select-Object TaskName, StateStateshould beReadyorRunning.
The ports reach the Windows browser through WSL2's localhost forwarding. The installation marks itself with deploy\docker\.wsl, so updates run with the same command take the WSL2 path again. In setup.exe, Without Docker Desktop (WSL2) on the prerequisite page takes the same path (silent: Spitfire-Setup.exe /S /ENGINE=wsl); the .msi installs with Docker Desktop only. Uninstall Spitfire removes Spitfire and the task, while the Ubuntu distribution stays; to delete it too, run wsl --unregister Ubuntu-24.04 (everything in it goes).
macOS: installer wizard (.dmg)
Download: Spitfire.dmg. It lands as
~/Downloads/Spitfire.dmg.Optionally check the signature (signed with Albiferro's Apple Developer ID and notarized). This prints
OK:spctl -a -t open --context context:primary-signature ~/Downloads/Spitfire.dmg 2>/dev/null && echo OKOn first open macOS asks whether you want to open an app downloaded from the Internet; press Open. "Apple could not verify …" means an old file; download it again.
Open the file, drag Spitfire Installer into Applications and open it.
The Checks page changes nothing. Without Docker press Install Docker for me → Yes, install: Terminal runs
brew install --cask docker(it may ask for your Mac password) and the wizard waits for Docker Desktop; without Homebrew the download page opens. If Docker is stopped press Start Docker (it waits up to 3 minutes). You accept Docker Desktop's agreement on its first start yourself.When every line is green, go through the licence, folder, settings and first admin pages with Continue and press Install.
The Finish page shows the address, the setup code and the installation details; take them with Copy the details, then Open Spitfire.
Success check, prints
OK:curl -fsS http://localhost:8470/readyz && echo OK
Opened again, the wizard finds the installation and offers Update, Repair and Uninstall. Log: ~/Library/Logs/Spitfire Installer/.
Windows: setup wizard (setup.exe / .msi)
- Download: Spitfire-Setup.exe.
- Run it. If Windows protected your PC appears, click More info.
- Click Run anyway.
- Pick a language. The first page is the prerequisite check and changes nothing. Without Docker press Install Docker for me (
winget install -e --id Docker.DockerDesktopruns in its own window; without winget the download page opens) or Without Docker Desktop (WSL2). If Docker is stopped press Start Docker, then Retry. - When every line is fine, go through licence, folder, settings (ports, number of runners, demo, APM), first admin (optional) and summary with Next and press Install.
- The Installation details page shows the address, the setup code, where
.envand the keys are and the backup command; take them with Copy. - Click Finish; with Open Spitfire ticked,
http://localhost:8470opens. - Success check: the Start menu shows Spitfire, Update Spitfire and Uninstall Spitfire; the page shows the sign-in screen.
Silent install
With the .msi (Intune, GPO or a script):
In PowerShell (no administrator needed):
irm https://usespitfire.com/download/Spitfire.msi -OutFile "$env:TEMP\Spitfire.msi"; Start-Process msiexec -Wait -ArgumentList '/i', "`"$env:TEMP\Spitfire.msi`"", '/qn', '/l*v', "`"$env:TEMP\spitfire-msi.log`"", 'PORT=8470', 'RUNNERS=2', 'LANG=en'Success check, prints
OK:if ((Invoke-WebRequest -UseBasicParsing http://localhost:8470/readyz).StatusCode -eq 204) { 'OK' }
With setup.exe: Spitfire-Setup.exe /S /PORT=8470 /RUNNERS=2. Exit code 0 means Spitfire answered at /readyz; the log is %USERPROFILE%\spitfire\logs\setup-*.log. Every setting left empty keeps the earlier install's value.
| MSI property | setup.exe switch | Meaning |
|---|---|---|
INSTALLFOLDER=C:\path\ |
/D=C:\path |
Install folder (default %USERPROFILE%\spitfire; /D= goes last) |
PORT=8470 GRPCPORT=8471 |
/PORT=8470 /GRPCPORT=8471 |
UI and runner ports |
RUNNERS=2 |
/RUNNERS=2 |
Number of local runners |
ADMINEMAIL= ADMINPASSWORD= |
/ADMIN_EMAIL= /ADMIN_PASSWORD= |
First admin; when empty it is created in the browser with the setup code |
WITHDEMO=1 / 0 |
/DEMO=1 / 0 |
Install / skip the demo app |
APM=1 / 0 |
/APM=1 / 0 |
Turn APM on / off |
LANG=tr / en |
/LANG=tr / en |
UI language |
| - | /ENGINE=wsl |
Install on Docker Engine inside WSL2 |
STARTDOCKER=1 |
/STARTDOCKER=1 |
Start a stopped Docker Desktop and wait (a silent install never installs Docker) |
SKIPDOCKERCHECK=1 |
/SKIPDOCKERCHECK |
Skip the Docker check (when you installed Docker another way) |
PURGE=1 (with msiexec /x) |
/PURGE (with uninstall-spitfire.exe /S) |
Delete the data too when uninstalling |
Without Docker, or with Docker stopped, a silent setup.exe exits with code 3 before copying any file; the reason is in %TEMP%\Spitfire-setup-precheck.log. The .msi does not install Docker; without Docker Desktop it stops before copying any file and says: Docker Desktop was not found; Spitfire runs on it and this setup does not install it. Install it: winget install -e --id Docker.DockerDesktop …. Install and start Docker, then run the .msi again.
The wizard and the .msi are published without a code signature, which is why SmartScreen warns. You can check the download against Spitfire-Setup.exe.sha256. The install is per user; Uninstall Spitfire asks before deleting data, and by default .env, backups and logs stay.
Common problems
When an install step fails (Docker stopped, the image did not pull, a port is busy…) the wizard and the .msi open an error window: the ERROR: and Fix: lines, the error code, the last lines of the log and the log path. Copy takes all of it, Open the log opens it. If you cannot solve it, e-mail the error code and the log file to support@usespitfire.com.
Symptom: the .msi stopped halfway, showed error 1722 and rolled back.
Cause: an install step failed; the .msi cannot put the reason in its own message. A first install is rolled back completely (half-created containers included); an update leaves the existing installation alone.
Fix: read the Spitfire error window that opens before 1722; if you missed it, look at the last lines of %TEMP%\Spitfire-setup-*.log (that copy survives even when the install folder is removed). Check the prerequisites with & ([scriptblock]::Create((irm https://spitfire.sh/ps))) docker -Check.