The launcher is now a self-contained installer with install, run, update, doctor and uninstall. Install downloads waggle-server-<version>-<target> .tar.gz, checks its SHA-256, unpacks it into a per-user program directory and writes a waggle-server command that runs the tool on the archive's own Node. Nothing is built on the user's machine and the data directory stays WAGGLE_DATA_DIR or ~/.waggle. scripts/build-server-archive.mjs packs the staged desktop sidecar payload with the built web UI and a manifest. The download location waits for the repository decision; until then install takes --from or WAGGLE_RELEASE_BASE_URL (ADR-0009). Removes install.sh, scripts/waggle-server.sh and their CI job, which the installer replaces, and the bin name clash with @waggle/cli.
2.7 KiB
2.7 KiB
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/wagglestarted 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.shcloned 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
- The release publishes one server archive per target:
windows-x64,macos-arm64,macos-x64andlinux-x64.scripts/build-server-archive.mjspacks the staged desktop payload, the built web UI underweb/and amanifest.jsonintowaggle-server-<version>-<target>.tar.gz, with a.sha256next to it. - The installer downloads and unpacks it.
packages/launcheris now a self-contained tool (waggle-server) that uses only Node's built-in modules:installdownloads the archive for this system, checks its SHA-256 and unpacks it into a per-user program directory, then writes awaggle-servercommand;run(the default) starts the server on the archive's own Node and opens the browser;doctorchecks the runtime, SQLite, the data directory, the port and the command;updateswaps in another version;uninstallremoves the program and keeps the data.
- 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
npxcall. - The data directory does not change:
WAGGLE_DATA_DIRor~/.waggle, as for the sidecar. - The download location waits for the repository decision (Q9). Until then
installtakes--from <path or URL>, andWAGGLE_RELEASE_BASE_URLpoints 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.shand their CI job are removed.- The release workflow must build the archive on each target system (P1.3d).
- Windows cannot replace a running program:
updateanduninstallthere run throughnpx, and the server must be stopped first.