docs: add the install guide and the memory guide (P2.4)

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.
This commit is contained in:
shumeiko.it
2026-11-01 01:50:35 +01:00
parent 9806afbced
commit 491df50a59
2 changed files with 433 additions and 0 deletions

257
docs/install.md Normal file
View File

@@ -0,0 +1,257 @@
# 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).