# ADR-0009: The installer delivers a prebuilt server archive - Status: Accepted - Date: 2026-11-01 ## Context The scope requires a Node-based install tool without Docker or Python (fixed decision 4), built on `packages/launcher` (P1.3c). Two install paths existed: - `npx @waggle-ai/waggle` started the server from npm. npm installed the server dependencies on the user's Node, so native modules could fall back to node-gyp, and the CUDA and Puppeteer download skips could not be set (ADR-0005, ADR-0008). The tool did not serve the web UI. - `install.sh` cloned the repository and built it on the user's machine. It needed git, npm and, for some prebuild mismatches, a compiler. It ran on Linux and macOS only. The desktop build already stages a complete sidecar payload: `service.js`, the pinned Node, the native modules and the production `node_modules` (ADR-0008). ## Decision 1. **The release publishes one server archive per target**: `windows-x64`, `macos-arm64`, `macos-x64` and `linux-x64`. `scripts/build-server-archive.mjs` packs the staged desktop payload, the built web UI under `web/` and a `manifest.json` into `waggle-server--.tar.gz`, with a `.sha256` next to it. 2. **The installer downloads and unpacks it.** `packages/launcher` is now a self-contained tool (`waggle-server`) that uses only Node's built-in modules: - `install` downloads the archive for this system, checks its SHA-256 and unpacks it into a per-user program directory, then writes a `waggle-server` command; - `run` (the default) starts the server on the archive's own Node and opens the browser; - `doctor` checks the runtime, SQLite, the data directory, the port and the command; - `update` swaps in another version; `uninstall` removes the program and keeps the data. 3. **Nothing is built on the user's machine.** The archive carries its own Node, so the user's Node (20 or newer) is needed only for the first `npx` call. 4. **The data directory does not change**: `WAGGLE_DATA_DIR` or `~/.waggle`, as for the sidecar. 5. **The download location waits for the repository decision (Q9).** Until then `install` takes `--from `, and `WAGGLE_RELEASE_BASE_URL` points it at a mirror. The project owner chose this over publishing the server to npm on 2026-11-01. ## Consequences - The installed server runs exactly the payload the desktop app ships and the release smoke tests. - An archive is about 130 MB (macOS arm64); it is downloaded once per version. - `install.sh`, `scripts/waggle-server.sh` and their CI job are removed. - The release workflow (`release.yml`) builds the archive on each target system and smoke-tests the installer against it. - Windows cannot replace a running program: `update` and `uninstall` there run through `npx`, and the server must be stopped first.