Skip to main content

​
Windows

FluffBuzz supports both native Windows and WSL2. WSL2 is the more stable path and recommended for the full experience — the CLI, Gateway, and tooling run inside Linux with full compatibility. Native Windows works for core CLI and Gateway use, with some caveats noted below. Native Windows companion apps are planned.

​
Native Windows status

Native Windows CLI flows are improving, but WSL2 is still the recommended path. What works well on native Windows today:
  • website installer via install.ps1
  • local CLI use such as fluffbuzz --version, fluffbuzz doctor, and fluffbuzz plugins list --json
  • embedded local-agent/provider smoke such as:
fluffbuzz agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."
Current caveats:
  • fluffbuzz onboard --non-interactive still expects a reachable local gateway unless you pass --skip-health
  • fluffbuzz onboard --non-interactive --install-daemon and fluffbuzz gateway install try Windows Scheduled Tasks first
  • if Scheduled Task creation is denied, FluffBuzz falls back to a per-user Startup-folder login item and starts the gateway immediately
  • if schtasks itself wedges or stops responding, FluffBuzz now aborts that path quickly and falls back instead of hanging forever
  • Scheduled Tasks are still preferred when available because they provide better supervisor status
If you want the native CLI only, without gateway service install, use one of these: 
fluffbuzz onboard --non-interactive --skip-health
fluffbuzz gateway run
If you do want managed startup on native Windows: 
fluffbuzz gateway install
fluffbuzz gateway status --json
If Scheduled Task creation is blocked, the fallback service mode still auto-starts after login through the current user’s Startup folder.

​
Gateway

​
Gateway service install (CLI)

Inside WSL2: 
fluffbuzz onboard --install-daemon
Or: 
fluffbuzz gateway install
Or: 
fluffbuzz configure
Select Gateway service when prompted. Repair/migrate: 
fluffbuzz doctor

​
Gateway auto-start before Windows login

For headless setups, ensure the full boot chain runs even when no one logs into Windows.

​
1) Keep user services running without login

Inside WSL: 
sudo loginctl enable-linger "$(whoami)"

​
2) Install the FluffBuzz gateway user service

Inside WSL: 
fluffbuzz gateway install

​
3) Start WSL automatically at Windows boot

In PowerShell as Administrator: 
schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM
Replace Ubuntu with your distro name from: 
wsl --list --verbose

​
Verify startup chain

After a reboot (before Windows sign-in), check from WSL: 
systemctl --user is-enabled fluffbuzz-gateway
systemctl --user status fluffbuzz-gateway --no-pager

​
Advanced: expose WSL services over LAN (portproxy)

WSL has its own virtual network. If another machine needs to reach a service running inside WSL (SSH, a local TTS server, or the Gateway), you must forward a Windows port to the current WSL IP. The WSL IP changes after restarts, so you may need to refresh the forwarding rule. Example (PowerShell as Administrator): 
$Distro = "Ubuntu-24.04"
$ListenPort = 2222
$TargetPort = 22

$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
if (-not $WslIp) { throw "WSL IP not found." }

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
  connectaddress=$WslIp connectport=$TargetPort
Allow the port through Windows Firewall (one-time): 
New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
  -Protocol TCP -LocalPort $ListenPort -Action Allow
Refresh the portproxy after WSL restarts: 
netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
  connectaddress=$WslIp connectport=$TargetPort | Out-Null
Notes:
  • SSH from another machine targets the Windows host IP (example: ssh user@windows-host -p 2222).
  • Remote nodes must point at a reachable Gateway URL (not 127.0.0.1); use fluffbuzz status --all to confirm.
  • Use listenaddress=0.0.0.0 for LAN access; 127.0.0.1 keeps it local only.
  • If you want this automatic, register a Scheduled Task to run the refresh step at login.

​
Step-by-step WSL2 install

​
1) Install WSL2 + Ubuntu

Open PowerShell (Admin): 
wsl --install
# Or pick a distro explicitly:
wsl --list --online
wsl --install -d Ubuntu-24.04
Reboot if Windows asks.

​
2) Enable systemd (required for gateway install)

In your WSL terminal: 
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF
Then from PowerShell: 
wsl --shutdown
Re-open Ubuntu, then verify: 
systemctl --user status

​
3) Install FluffBuzz (inside WSL)

Follow the Linux Getting Started flow inside WSL: 
git clone https://github.com/fluffbuzz/fluffbuzz.git
cd fluffbuzz
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
fluffbuzz onboard
Full guide: Getting Started

​
Windows companion app

We do not have a Windows companion app yet. Contributions are welcome if you want contributions to make it happen.