docs: recommend WSL2 for Windows installs

README.md

@@ -22,7 +22,7 @@ If you want a personal, single-user assistant that feels local, fast, and always
 
 [Website](https://clawdbot.com) · [Docs](https://docs.clawd.bot) · Getting Started: [https://docs.clawd.bot/getting-started](https://docs.clawd.bot/getting-started) · Updating: [https://docs.clawd.bot/updating](https://docs.clawd.bot/updating) · Showcase: [https://docs.clawd.bot/showcase](https://docs.clawd.bot/showcase) · FAQ: [https://docs.clawd.bot/faq](https://docs.clawd.bot/faq) · Wizard: [https://docs.clawd.bot/wizard](https://docs.clawd.bot/wizard) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://docs.clawd.bot/docker](https://docs.clawd.bot/docker) · Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
 
-Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux**.
+Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Linux, and Windows (via WSL2; strongly recommended)**.
 Works with npm, pnpm, or bun.
 New install? Start here: https://docs.clawd.bot/getting-started
 
@@ -369,7 +369,7 @@ Use these when you’re past the onboarding flow and want the deeper reference.
 - [Wire external triggers via the webhook surface.](https://docs.clawd.bot/webhook)
 - [Set up Gmail Pub/Sub triggers.](https://docs.clawd.bot/gmail-pubsub)
 - [Learn the macOS menu bar companion details.](https://docs.clawd.bot/mac/menu-bar)
-- [Platform guides: Windows](https://docs.clawd.bot/windows), [Linux](https://docs.clawd.bot/linux), [macOS](https://docs.clawd.bot/macos), [iOS](https://docs.clawd.bot/ios), [Android](https://docs.clawd.bot/android)
+- [Platform guides: Windows (WSL2)](https://docs.clawd.bot/windows), [Linux](https://docs.clawd.bot/linux), [macOS](https://docs.clawd.bot/macos), [iOS](https://docs.clawd.bot/ios), [Android](https://docs.clawd.bot/android)
 - [Debug common failures with the troubleshooting guide.](https://docs.clawd.bot/troubleshooting)
 - [Review security guidance before exposing anything.](https://docs.clawd.bot/security)
 
@@ -416,7 +416,7 @@ Use these when you’re past the onboarding flow and want the deeper reference.
 - [macOS voice wake](https://docs.clawd.bot/mac/voicewake)
 - [iOS node](https://docs.clawd.bot/ios)
 - [Android node](https://docs.clawd.bot/android)
-- [Windows app](https://docs.clawd.bot/windows)
+- [Windows (WSL2)](https://docs.clawd.bot/windows)
 - [Linux app](https://docs.clawd.bot/linux)
 
 ## Email hooks (Gmail)

docs/gateway/doctor.md

@@ -14,7 +14,7 @@ read_when:
 - Detects deprecated config keys and offers to migrate them.
 - Migrates legacy `~/.clawdis/clawdis.json` when no Clawdbot config exists.
 - Checks sandbox Docker images when sandboxing is enabled (offers to build or switch to legacy names).
-- Detects legacy Clawdis services (launchd/systemd/schtasks) and offers to migrate them.
+- Detects legacy Clawdis services (launchd/systemd; legacy schtasks for native Windows) and offers to migrate them.
 - On Linux, checks if systemd user lingering is enabled and can enable it (required to keep the Gateway alive after logout).
 - Migrates legacy on-disk state layouts (sessions, agentDir, provider auth dirs) into the current per-agent/per-account structure.
 
@@ -63,6 +63,6 @@ cat ~/.clawdbot/clawdbot.json
 ```
 
 ## Legacy service migrations
-Doctor checks for older Clawdis gateway services (launchd/systemd/schtasks).
+Doctor checks for older Clawdis gateway services (launchd/systemd/schtasks). WSL2 installs use systemd.
 If found, it offers to remove them and install the Clawdbot service using the current gateway port.
 Remote mode skips the install step, and Nix mode only reports what it finds.

docs/gateway/index.md

@@ -184,7 +184,7 @@ Enable lingering (required so the user service survives logout/idle):
 ```
 sudo loginctl enable-linger youruser
 ```
-Onboarding runs this on Linux (may prompt for sudo; writes `/var/lib/systemd/linger`).
+Onboarding runs this on Linux/WSL2 (may prompt for sudo; writes `/var/lib/systemd/linger`).
 Then enable the service:
 ```
 systemctl --user enable --now clawdbot-gateway.service
@@ -199,9 +199,9 @@ sudo systemctl daemon-reload
 sudo systemctl enable --now clawdbot-gateway.service
 ```
 
-## Supervision (Windows scheduled task)
+## Windows (WSL2)
-- Onboarding installs a Scheduled Task named `Clawdbot Gateway` (runs on user logon).
+
-- Requires a logged-in user session; for headless setups use a system service or a task configured to run without a logged-in user (not shipped).
+Windows installs should use **WSL2** and follow the Linux systemd section above.
 
 ## Operational checks
 - Liveness: open WS and send `req:connect` → expect `res` with `payload.type="hello-ok"` (with snapshot).
@@ -219,7 +219,7 @@ sudo systemctl enable --now clawdbot-gateway.service
 - `clawdbot gateway send --to <num> --message "hi" [--media-url ...]` — send via Gateway (idempotent).
 - `clawdbot gateway agent --message "hi" [--to ...]` — run an agent turn (waits for final by default).
 - `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
-- `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd/schtasks).
+- `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
 - Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
 
 ## Migration guidance

docs/index.md

@@ -177,7 +177,7 @@ Example:
   - [macOS app](https://docs.clawd.bot/platforms/macos)
   - [iOS app](https://docs.clawd.bot/platforms/ios)
   - [Android app](https://docs.clawd.bot/platforms/android)
-  - [Windows app](https://docs.clawd.bot/platforms/windows)
+  - [Windows (WSL2)](https://docs.clawd.bot/platforms/windows)
   - [Linux app](https://docs.clawd.bot/platforms/linux)
 - Ops and safety:
   - [Sessions](https://docs.clawd.bot/concepts/session)

docs/install/updating.md

@@ -12,7 +12,7 @@ Clawdbot is moving fast (pre “1.0”). Treat updates like shipping infra: upda
 ## Before you update
 
 - Know how you installed: **npm** (global) vs **from source** (git clone).
-- Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd/Scheduled Task).
+- Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd).
 - Snapshot your tailoring:
   - Config: `~/.clawdbot/clawdbot.json`
   - Credentials: `~/.clawdbot/credentials/`
@@ -68,7 +68,7 @@ Typical things it does:
 - Migrate deprecated config keys / legacy config file locations.
 - Audit DM policies and warn on risky “open” settings.
 - Check Gateway health and can offer to restart.
-- Detect and migrate older gateway services (launchd/systemd/schtasks) to current Clawdbot services.
+- Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current Clawdbot services.
 - On Linux, ensure systemd user lingering (so the Gateway survives logout).
 
 Details: [Doctor](/doctor)
@@ -86,7 +86,7 @@ clawdbot gateway --port 18789
 If you’re supervised:
 - macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`
 - Linux systemd user service: `systemctl --user restart clawdbot-gateway.service`
-- Windows: restart the `Clawdbot Gateway` Scheduled Task (Task Scheduler)
+- Windows (WSL2): `systemctl --user restart clawdbot-gateway.service`
 
 Runbook + exact service labels: [Gateway runbook](/gateway)
 

docs/platforms/windows.md

@@ -1,11 +1,73 @@
 ---
-summary: "Windows app status + contribution call"
+summary: "Windows (WSL2) setup + companion app status"
 read_when:
+  - Installing Clawdbot on Windows
   - Looking for Windows companion app status
   - Planning platform coverage or contributions
 ---
-# Windows App
+# Windows (WSL2)
 
-Clawdbot core is fully supported on Windows. The core is written in TypeScript, so it runs anywhere Node runs.
+Clawdbot runs on Windows **via WSL2** (Ubuntu recommended). WSL2 is **strongly
+recommended**; native Windows installs are untested and more problematic. Use
+WSL2 and follow the Linux flow inside it.
 
-We do not have a Windows companion app yet. It is planned, and we would love contributions to make it happen.
+## How to install this correctly
+
+Start here (official WSL2 guide): https://learn.microsoft.com/windows/wsl/install
+
+### 1) Install WSL2 + Ubuntu
+
+Open PowerShell (Admin):
+
+```powershell
+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 daemon install)
+
+In your WSL terminal:
+
+```bash
+sudo tee /etc/wsl.conf >/dev/null <<'EOF'
+[boot]
+systemd=true
+EOF
+```
+
+Then from PowerShell:
+
+```powershell
+wsl --shutdown
+```
+
+Re-open Ubuntu, then verify:
+
+```bash
+systemctl --user status
+```
+
+### 3) Install Clawdbot (inside WSL)
+
+Follow the Linux Getting Started flow inside WSL:
+
+```bash
+git clone https://github.com/clawdbot/clawdbot.git
+cd clawdbot
+pnpm install
+pnpm ui:install
+pnpm ui:build
+pnpm build
+pnpm clawdbot onboard
+```
+
+Full guide: [Getting Started](/getting-started)
+
+## Windows companion app
+
+We do not have a Windows companion app yet. It is planned, and we would love
+contributions to make it happen.

docs/start/clawd.md

@@ -212,6 +212,6 @@ Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`).
 - macOS menu bar companion: [Clawdbot macOS app](/macos)
 - iOS node app: [iOS app](/ios)
 - Android node app: [Android app](/android)
-- Windows status: [Windows app](/windows)
+- Windows status: [Windows (WSL2)](/windows)
 - Linux status: [Linux app](/linux)
 - Security: [Security](/security)

docs/start/faq.md

@@ -28,11 +28,11 @@ Your **workspace** (AGENTS.md, memory files, skills) is separate — configured
 
 ### What platforms does Clawdbot run on?
 
-**macOS and Linux** are the primary targets. Anywhere Node.js 22+ runs should work in theory.
+**macOS and Linux** are the primary targets. On Windows, use **WSL2** (Ubuntu recommended).
 
 - **macOS** — Fully supported, most tested
 - **Linux** — Works great, common for VPS/server deployments
-- **Windows** — Should work but largely untested! You're in pioneer territory 🤠
+- **Windows (WSL2)** — WSL2 is strongly recommended; native Windows installs are untested and more problematic
 
 Some features are platform-specific:
 - **iMessage** — macOS only (uses `imsg` CLI)
@@ -52,6 +52,18 @@ The gateway is just shuffling messages around. A Raspberry Pi 4 can run it. For
 clawdbot gateway
 ```
 
+### How do I install on Windows?
+
+Use **WSL2** (Ubuntu recommended) and follow the Linux flow inside WSL. Quick start:
+
+```powershell
+wsl --install
+```
+
+Then open Ubuntu and run the normal Getting Started steps.
+
+Full guide: [Windows (WSL2)](/windows)
+
 ### How do I install on Linux without Homebrew?
 
 Build CLIs from source! Example for `gogcli`:
@@ -494,9 +506,10 @@ Onboarding attempts to enable lingering; if it’s still off, run:
 sudo loginctl enable-linger $USER
 ```
 
-**macOS/Windows**
+**macOS/WSL2**
 
-Gateway daemons run in the user session by default. Keep the user logged in.
+Gateway daemons run in the user session by default. Keep the user logged in
+(WSL2 services stop when the WSL VM shuts down).
 Headless/system services are not configured out of the box.
 
 ### Processes keep restarting after I kill them

docs/start/getting-started.md

@@ -26,6 +26,7 @@ If you want the deeper reference pages, jump to: [Wizard](/wizard), [Setup](/set
 - Git
 
 macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
+Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested and more problematic. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/windows).
 
 ## 1) Check out from source
 
@@ -63,7 +64,7 @@ What you’ll choose:
 - **Local vs Remote** gateway
 - **Auth**: Anthropic OAuth or OpenAI OAuth (recommended), API key (optional), or skip for now
 - **Providers**: WhatsApp QR login, bot tokens, etc.
-- **Daemon**: optional background install (launchd/systemd/Task Scheduler)
+- **Daemon**: optional background install (launchd/systemd; WSL2 uses systemd)
   - **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp)
 
 Wizard doc: [Wizard](/wizard)

docs/start/hubs.md

@@ -131,7 +131,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [macOS Peekaboo plan](https://docs.clawd.bot/platforms/mac/peekaboo)
 - [iOS node](https://docs.clawd.bot/platforms/ios)
 - [Android node](https://docs.clawd.bot/platforms/android)
-- [Windows app](https://docs.clawd.bot/platforms/windows)
+- [Windows (WSL2)](https://docs.clawd.bot/platforms/windows)
 - [Linux app](https://docs.clawd.bot/platforms/linux)
 - [Web surfaces](https://docs.clawd.bot/web)
 

docs/start/onboarding.md

@@ -187,3 +187,11 @@ chmod 600 ~/.clawdbot/credentials/oauth.json
 | `accessToken` | `access` |
 | `refreshToken` | `refresh` |
 | `expiresAt` | `expires` |
+
+## Workspace backup (recommended)
+
+We suggest creating a **private GitHub repository** to back up the agent
+workspace. The agent is really good at keeping a git repo in shape, and GitHub
+is the perfect place for it. Keep it **private**.
+
+Setup steps: https://docs.clawd.bot/concepts/agent-workspace

docs/start/wizard.md

@@ -7,7 +7,8 @@ read_when:
 
 # Onboarding Wizard (CLI)
 
-The onboarding wizard is the **recommended** way to set up Clawdbot on any OS.
+The onboarding wizard is the **recommended** way to set up Clawdbot on macOS,
+Linux, or Windows (via WSL2; strongly recommended).
 It configures a local Gateway or a remote Gateway connection, plus providers, skills,
 and workspace defaults in one guided flow.
 
@@ -30,7 +31,7 @@ clawdbot configure
 - Workspace location + bootstrap files
 - Gateway settings (port/bind/auth/tailscale)
 - Providers (WhatsApp, Telegram, Discord, Signal)
-- Daemon install (LaunchAgent / systemd user unit / Scheduled Task)
+- Daemon install (LaunchAgent / systemd user unit)
 - Health check
 - Skills (recommended)
 
@@ -77,11 +78,9 @@ It does **not** install or change anything on the remote host.
 6) **Daemon install**
    - macOS: LaunchAgent
      - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
-   - Linux: systemd user unit
+   - Linux (and Windows via WSL2): systemd user unit
      - Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
-   - Windows: Scheduled Task
-     - Runs on user logon; headless/system services are not configured by default.
    - **Runtime selection:** Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp).
 
 7) **Health check**
@@ -144,7 +143,7 @@ The wizard can install `signal-cli` from GitHub releases:
 Notes:
 - JVM builds require **Java 21**.
 - Native builds are used when available.
-- Windows auto‑install is not supported yet (manual install required).
+- Windows uses WSL2; signal-cli install follows the Linux flow inside WSL.
 
 ## What the wizard writes
 

src/commands/onboard.ts

@@ -10,6 +10,15 @@ export async function onboardCommand(
   runtime: RuntimeEnv = defaultRuntime,
 ) {
   assertSupportedRuntime(runtime);
+  if (process.platform === "win32") {
+    runtime.log(
+      [
+        "Windows detected.",
+        "WSL2 is strongly recommended; native Windows is untested and more problematic.",
+        "Guide: https://docs.clawd.bot/windows",
+      ].join("\n"),
+    );
+  }
 
   if (opts.nonInteractive) {
     await runNonInteractiveOnboarding(opts, runtime);