# Installing Waggle There are two ways to install Waggle. Both run the same server and the same web UI, and both keep your data in the same place. | | Desktop app | Server installer | |---|---|---| | What you get | A Waggle window, started from the Start menu, Applications or your launcher | A `waggle-server` command; you use Waggle in your browser | | Needs | Nothing else | Node.js 20 or newer for the first `npx` call only | | Formats | Windows `.exe` and `.msi`, macOS `.dmg`, Linux `.deb` and `.AppImage` | One archive per system, downloaded by the installer | Supported systems in this release: Windows x64, macOS on Apple silicon (arm64) and Intel (x64), and Linux x64 with glibc (for example Debian, Ubuntu, Fedora). Other systems, such as Windows on ARM or Linux on ARM, have no build. Neither way needs Python, Docker or a compiler. Each build carries its own Node.js runtime (22.23.2) and the native modules that match it. > **Unsigned first release.** The installers of the first community release are not signed. > Windows and macOS warn about them. The sections below show how to get past the warning. > Download Waggle only from the project's release page. ## Desktop app ### Windows 1. Download `Waggle__x64-setup.exe`. A `.msi` package is also available; use the `.exe` unless you deploy with MSI tools. The `.exe` installs for the current user and does not need administrator rights. 2. If the browser warns that the file is not commonly downloaded, choose to keep it (in Edge: **...** → **Keep**). 3. Run the installer. SmartScreen shows "Windows protected your PC". Choose **More info**, then **Run anyway**. 4. Start Waggle from the Start menu. Waggle uses the WebView2 runtime, which ships with current Windows 10 and 11. ### macOS 1. Download the `.dmg` for your Mac: `Waggle__aarch64.dmg` for Apple silicon, `Waggle__x64.dmg` for Intel. (Apple menu → **About This Mac** shows the chip.) 2. Open the `.dmg` and drag **Waggle** to **Applications**. 3. Open Waggle. Because the app is not signed, macOS blocks the first launch: - macOS 15 and later: after the warning, open **System Settings** → **Privacy & Security**, scroll to the message about Waggle and choose **Open Anyway**. - Earlier versions: Control-click (or right-click) Waggle in Applications, choose **Open**, then **Open** again in the dialog. - If macOS says the app "is damaged" or still refuses, remove the download quarantine flag in Terminal and open it again: ```bash xattr -dr com.apple.quarantine /Applications/Waggle.app ``` You only need to do this once. ### Linux Debian, Ubuntu and other distributions with apt: ```bash sudo apt install ./Waggle__amd64.deb ``` apt installs the libraries the app needs (WebKitGTK and GTK). Start Waggle from your application launcher. AppImage, for other distributions: ```bash chmod +x Waggle__amd64.AppImage ./Waggle__amd64.AppImage ``` An AppImage needs FUSE 2. If it fails with a FUSE error, install it (`libfuse2` on Ubuntu 22.04, `libfuse2t64` on Ubuntu 24.04 and later, `fuse-libs` on Fedora). Linux packages are not signed. If the release page lists SHA-256 checksums, compare them before you install: ```bash sha256sum Waggle__amd64.deb ``` ### What the desktop app does on start The window shows "Starting Waggle…" while the app starts its own server in the background. The server listens on `127.0.0.1` port 3333, or on another free port if 3333 is taken. Its log is in `~/.waggle/logs/service.log` (on Windows `%USERPROFILE%\.waggle\logs\service.log`). ### Update the desktop app The desktop app does not update itself in this release. Quit Waggle, then install the new version over the old one: - Windows: run the new installer. - macOS: drag the new Waggle to Applications and replace the old one. - Linux: `sudo apt install ./Waggle__amd64.deb`, or replace the AppImage file. Your data is not touched. ### Uninstall the desktop app - Windows: **Settings** → **Apps** → **Installed apps** (**Apps & features** on Windows 10) → **Waggle** → **Uninstall**. The uninstaller always keeps your data, even if you tick its "Delete app data" box. - macOS: quit Waggle and move **Waggle** from Applications to the Trash. - Linux: remove the package (`sudo apt remove waggle`; `dpkg -l | grep -i waggle` shows its name), or delete the AppImage file. Your data stays in the data directory; see [Where your data lives](#where-your-data-lives). ## Server installer The server installer puts the Waggle server on your computer and starts it. You then use Waggle in your browser at http://localhost:3333. > **Temporary names.** The package name `@waggle-ai/waggle` and the command `waggle-server` are > working names until the product name is decided. The installer also has no default download > location yet, because the location of the public repository is not decided. Until then, pass > the archive with `--from`, as shown below. ### Install You need Node.js 20 or newer for this one command. After that, Waggle runs on its own Node.js runtime and does not use yours. ```bash npx @waggle-ai/waggle install --from ``` The archive for your system is named `waggle-server--.tar.gz`, where `` is `windows-x64`, `macos-arm64`, `macos-x64` or `linux-x64`. A `.sha256` file is published next to it. The installer: 1. checks the archive against its SHA-256 (for a URL it reads `.sha256`; for a local file it reads `.sha256` if one is next to it). A mismatch stops the install. Pass `--sha256 ` to give the checksum yourself; 2. unpacks it into a program directory; 3. writes the `waggle-server` command. | System | Program directory | `waggle-server` command | |---|---|---| | Windows | `%LOCALAPPDATA%\Waggle\server` | `%LOCALAPPDATA%\Waggle\server\bin\waggle-server.cmd` | | macOS | `~/Library/Application Support/Waggle/server` | `~/.local/bin/waggle-server` | | Linux | `~/.local/share/waggle/server` (or `$XDG_DATA_HOME/waggle/server`) | `~/.local/bin/waggle-server` | The installer never edits your `PATH`. If the command's directory is not on your `PATH`, it prints the full path to run and the directory to add. Once a download location exists, `npx @waggle-ai/waggle install` without `--from` downloads the archive for your system. `WAGGLE_RELEASE_BASE_URL` points it at a mirror. ### Run ```bash waggle-server ``` This is the same as `waggle-server run`. It starts the server, waits until it answers and opens http://localhost:3333 in your browser. The server runs in that terminal; press Ctrl+C to stop it. It listens on this computer only (`127.0.0.1`). | Option | Meaning | |---|---| | `--port `, `-p` | Use another port (default 3333) | | `--no-open` | Do not open the browser | | `--data-dir ` | Keep data in another directory (default `$WAGGLE_DATA_DIR` or `~/.waggle`) | | `--dir ` | Use a program directory other than the default | If Waggle already runs on the port, `waggle-server` only opens the browser. ### Check the installation ```bash waggle-server doctor ``` `doctor` checks that this system has a build, the installed files, the bundled Node.js runtime, that SQLite loads, that the data directory is writable, the port, and whether `waggle-server` is on your `PATH`. It exits with an error code if a check fails. ### Update `update` installs the version of the installer you run it with: ```bash npx @waggle-ai/waggle@latest update # once a download location exists waggle-server update --from # a specific archive ``` Your data is not touched. On Windows a running program cannot be replaced: stop the server first, and run `update` through `npx`, not through the installed `waggle-server`. ### Uninstall ```bash waggle-server uninstall ``` This removes the program directory and the `waggle-server` command. Your data stays in the data directory. On Windows, stop the server and run `npx @waggle-ai/waggle uninstall`. All commands also take `--help` and `--version`. ## First launch Waggle opens a short setup: 1. **Welcome** and **Who are you**: your name, role and the kind of work you do, kept on this computer in your profile. 2. **Model**: choose how Waggle thinks (see below). You can skip this step, but chat stays unavailable until a model is set up. 3. **Pick a starting point**: a template for your first workspace (for example Research Hub, Sales Pipeline or Engineering), or **Blank Workspace**. 4. **What's first?**: give the agent its first task, or pick a suggestion. ### Choose a model - **API key.** Paste a key from a provider you already use: Anthropic, OpenAI, Google, DeepSeek, xAI, Mistral, Alibaba (Qwen), MiniMax, Zhipu (GLM), Moonshot (Kimi), Perplexity or OpenRouter. Waggle checks the key with the provider and stores it encrypted on this computer. Requests go from your computer straight to that provider. - **Local model.** Choose **Install private runtime**. Waggle downloads the official Ollama runtime into its data directory, checks the download's checksum and runs it for you. Then download a model (Waggle suggests one that fits your hardware). Nothing else needs to be installed, and chats stay on your computer. The downloads are large: the Linux runtime alone is about 1.4 GB, and a model adds several GB. If you already run Ollama yourself, Waggle uses it. You can change both later in **Settings** → **Models**. Keys are also listed in the **Vault**. ### Analytics Release builds may carry a key for product analytics. If yours does, Waggle asks once whether it may send usage analytics. Nothing is sent until you choose **Allow**. If you allow it, Waggle sends one event when you finish the setup, with the template, persona and model you chose. Your chats, files and memories are never sent. You can turn analytics off again in **Settings** → **General** → **Privacy & Telemetry**. Builds from source have no key: they never ask and never send. ## Where your data lives Both ways of installing use one data directory: `~/.waggle` (on Windows `%USERPROFILE%\.waggle`). Set `WAGGLE_DATA_DIR` to use another directory; the server installer also takes `--data-dir`. | Path in the data directory | What it holds | |---|---| | `config.json` | Settings | | `vault.json`, `.vault-key` | Provider keys and connector credentials, encrypted with AES-256-GCM | | `waggle.db` | Automations, notifications, cost tracking, your profile card and task list | | `memory/` | Your memories (see [memory.md](memory.md)) | | `workspaces//` | Each workspace: settings, chat sessions (`sessions/*.jsonl`) and files | | `skills/`, `plugins/` | Installed skills and plugins | | `marketplace.db` | The marketplace catalog | | `models/` | The embedding model used by memory, downloaded on first use; local model weights in `models/ollama/` | | `runtimes/ollama/` | The Waggle-managed Ollama runtime | | `channels/`, `browsers/` | Messaging channel sessions, and a browser downloaded for WhatsApp if none is installed | | `logs/` | The desktop app's server log | Uninstalling Waggle, either way, keeps this directory. To remove your data, quit Waggle and delete the directory, or use **Settings** → **General** → **Erase all my data**, which wipes it the next time Waggle starts. To move Waggle to another computer, quit it and copy the whole directory. The commercial edition of Waggle uses the same default directory. If you use both on one computer, give the community edition its own directory with `WAGGLE_DATA_DIR`. ## Run from source See the [README](../README.md#run-from-source) and [CONTRIBUTING.md](../CONTRIBUTING.md). ## Problems See [troubleshooting](guides/troubleshooting.md).