Files
waggle-os/docs/install.md

12 KiB

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_<version>_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_<version>_aarch64.dmg for Apple silicon, Waggle_<version>_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:

      xattr -dr com.apple.quarantine /Applications/Waggle.app
      

You only need to do this once.

Linux

Debian, Ubuntu and other distributions with apt:

sudo apt install ./Waggle_<version>_amd64.deb

apt installs the libraries the app needs (WebKitGTK and GTK). Start Waggle from your application launcher.

AppImage, for other distributions:

chmod +x Waggle_<version>_amd64.AppImage
./Waggle_<version>_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:

sha256sum Waggle_<version>_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_<new version>_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.

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.

npx @waggle-ai/waggle install --from <archive path or URL>

The archive for your system is named waggle-server-<version>-<target>.tar.gz, where <target> 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 <URL>.sha256; for a local file it reads <file>.sha256 if one is next to it). A mismatch stops the install. Pass --sha256 <hex> 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

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 <number>, -p Use another port (default 3333)
--no-open Do not open the browser
--data-dir <path> Keep data in another directory (default $WAGGLE_DATA_DIR or ~/.waggle)
--dir <path> Use a program directory other than the default

If Waggle already runs on the port, waggle-server only opens the browser.

Check the installation

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:

npx @waggle-ai/waggle@latest update                  # once a download location exists
waggle-server update --from <archive path or URL>    # 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

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)
workspaces/<id>/ 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 and CONTRIBUTING.md.

Problems

See troubleshooting.