The release publishes the server archive and the desktop installers under one tag, and the installer looks for the release named after its own version, so both now carry 1.0.0.
5.3 KiB
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.
- Node.js 22, 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 through rustup, stable 1.94 or newer, with the default host
x86_64-pc-windows-msvc. - Visual Studio 2022 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:
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:
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:
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:
git -C C:\w\waggle-os pull C:\path\to\waggle-oss.bundle oss/community-edition
3. Build
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:
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-<version>-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:
node scripts/release-smoke.mjs desktop --app "$env:LOCALAPPDATA\Waggle\waggle.exe"
4. Check the result
- 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.
- Start Waggle from the Start menu. The window should move past "Starting Waggle…" to the Home screen.
- If it stays on "Starting Waggle…", close it and take the log from
%USERPROFILE%\.waggle\logs\service.log. - Chat needs a model: an API key in Settings → Models (Provider Keys), or a running Ollama.
Waggle keeps its data in %USERPROFILE%\.waggle.
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. |