# Building the Windows desktop app How to build the Waggle desktop installer for Windows from the `oss/community-edition` branch. The build has to run on Windows: the packaging scripts take the bundled Node.js runtime and the native modules (better-sqlite3, onnxruntime) from the machine they run on, so a build made on macOS would ship macOS binaries. The release workflow (`.github/workflows/release.yml`) runs the same build on GitHub's `windows-latest` runner for every `v*` tag and for pull requests that touch the desktop app. It has not run yet; the first build is part of the week 3 acceptance. Record what fails in `docs/oss/upstream-fixes.md` or `docs/oss/baseline.md`. ## 1. Prepare the machine - Windows 10 or 11, x64, with about 20 GB of free disk space. - [Git for Windows](https://git-scm.com/download/win). - [Node.js 22](https://nodejs.org/en/download), x64. Use 22.23.2 if you can: the installer bundles exactly this version, CI uses it, and the build checks that the bundled runtime can load the native modules installed by your Node. - [Rust](https://rustup.rs) through rustup, stable 1.94 or newer, with the default host `x86_64-pc-windows-msvc`. - [Visual Studio 2022 Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the **Desktop development with C++** workload (MSVC and the Windows SDK). Rust links with it, and npm uses it if a native module has to be compiled. - WebView2 Runtime. It ships with current Windows 10 and 11. Run every command below in **PowerShell**, not Git Bash. The build unpacks the Node.js zip with `tar`; Windows' own `tar` reads zip files, the GNU `tar` in Git Bash does not. Check the tools: ```powershell node --version # v22.x rustc --version # 1.94 or newer cargo --version git --version ``` ## 2. Get the code The branch is not on a shared remote, so copy it as a git bundle. On the machine that has the repository: ```bash git bundle create waggle-oss.bundle oss/community-edition ``` The bundle holds the full history, including the leaked Stripe secret (UF-005). Copy it to the Windows machine directly and do not upload it anywhere. On Windows, clone into a short path; `node_modules` and the Rust `target` folder produce long paths: ```powershell git clone --branch oss/community-edition C:\path\to\waggle-oss.bundle C:\w\waggle-os ``` To update later, make a new bundle and pull from it: ```powershell git -C C:\w\waggle-os pull C:\path\to\waggle-oss.bundle oss/community-edition ``` ## 3. Build ```powershell cd C:\w\waggle-os npm ci cd app npm ci npm run tauri:build:win -- --bundles nsis ``` `tauri:build:win` downloads and verifies the Node.js 22.23.2 runtime, bundles the sidecar, copies the native modules, builds the web UI and then the Tauri shell. The first run compiles the Rust shell from scratch and takes much longer than later runs. `--bundles nsis` builds only the NSIS installer, the one the app is configured for (a per-user install without administrator rights). Without the flag Tauri also builds an MSI, for which it downloads WiX; the release workflow builds both (`--bundles nsis,msi`). The installer: ``` app\src-tauri\target\x86_64-pc-windows-msvc\release\bundle\nsis\Waggle_1.0.0_x64-setup.exe ``` The same staged files make the server archive that the installer tool (`packages/launcher`) installs. To build it and run the release workflow's smoke tests: ```powershell cd C:\w\waggle-os npm run build --workspace @waggle-ai/waggle node scripts/build-server-archive.mjs node scripts/release-smoke.mjs installer ``` The archive is `artifacts\waggle-server--windows-x64.tar.gz`. The installer test installs it into a temporary folder, runs `doctor`, starts the server on a free port and uninstalls it. After installing the app (section 4), the desktop test starts it, waits until its sidecar answers on port 3333, then stops both. Close Waggle first so the port is free: ```powershell node scripts/release-smoke.mjs desktop --app "$env:LOCALAPPDATA\Waggle\waggle.exe" ``` ## 4. Check the result 1. Run the installer. It is not signed, so SmartScreen shows "Windows protected your PC": choose **More info**, then **Run anyway**. Waggle installs for the current user. 2. Start Waggle from the Start menu. The window should move past "Starting Waggle…" to the Home screen. 3. If it stays on "Starting Waggle…", close it and take the log from `%USERPROFILE%\.waggle-community\logs\service.log`. 4. Chat needs a model: an API key in Settings → Models (Provider Keys), or a running Ollama. Waggle keeps its data in `%USERPROFILE%\.waggle-community`. ## Troubleshooting | Symptom | Fix | |---|---| | `link.exe` not found, or a Rust linker error | Install the **Desktop development with C++** workload of the Build Tools. | | `npm ci` compiles better-sqlite3 and fails | The prebuilt binary could not be downloaded. Check the network or proxy; compiling it needs the C++ workload and Python 3. | | `[bundle-node]` reports an ABI or architecture mismatch | The Node.js you build with is not 22.x x64. Install 22.23.2. | | `tar` cannot open the Node.js archive | The build ran in Git Bash. Use PowerShell. | | Errors about paths that are too long | Clone to a shorter folder such as `C:\w\waggle-os`. | | Files in `target` are locked during the build | Antivirus is scanning them. Run the build again, or exclude the folder. |