docs/install.md covers both ways to install (the Tauri desktop packages and the server installer), the unsigned-installer warnings on each system, first launch, the data directory, update and uninstall. docs/memory.md describes the memory contract, its mem0 implementation, where mem0 keeps its files, recall and background fact extraction.
258 lines
11 KiB
Markdown
258 lines
11 KiB
Markdown
# 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:
|
|
|
|
```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_<version>_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_<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:
|
|
|
|
```bash
|
|
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`).
|
|
|
|
## 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 <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
|
|
|
|
```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 <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
|
|
|
|
```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 <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
|
|
|
|
```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/<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](../README.md#run-from-source) and [CONTRIBUTING.md](../CONTRIBUTING.md).
|
|
|
|
## Problems
|
|
|
|
See [troubleshooting](guides/troubleshooting.md).
|