Add ADR-0011: the community edition defaults to ~/.waggle-community, a temporary name that follows the product-name decision (Q8), and copies nothing from the commercial ~/.waggle. It supersedes point 4 of ADR-0009 and closes the pending "separate data directory" decision. Update the install guide, troubleshooting, capabilities, memory, architecture, the Windows build notes, THREAT_MODEL, README, .env.example and the changelog. Log UF-068 (Open): marketplace skills and plugins ignore a custom data directory.
2.8 KiB
2.8 KiB
ADR-0009: The installer delivers a prebuilt server archive
- Status: Accepted; point 4 superseded by ADR-0011
- 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 (
release.yml) builds the archive on each target system and smoke-tests the installer against it. - Windows cannot replace a running program:
updateanduninstallthere run throughnpx, and the server must be stopped first.