The architecture guide, AGENTS.md and the threat model said releases were built by hand or Windows-first; ADR-0009 still listed the release workflow as future work. The Windows build guide named the missing Settings > API Keys tab.
12 KiB
Architecture
How the community edition of Waggle is put together: the parts, how a chat turn flows through
them, where data lives and how a release is built. The decisions behind it are in
docs/oss/adr/; AGENTS.md lists the status of every
package.
Overview
Browser tab or Tauri window
┌──────────────────────────┐
│ Web UI (apps/web, React) │
└────────────┬─────────────┘
│ HTTP + Server-Sent Events, bearer session token
▼
┌─────────────────────────────────────────────────────────────┐
│ Sidecar: Fastify on Node.js, 127.0.0.1:3333 │
│ (packages/server/src/local) │
│ │
│ agent runtime ─────── built-in provider proxy ──► provider │
│ (packages/agent) (/v1/chat/completions) APIs or │
│ Ollama │
│ MemoryStore ──► @waggle/memory-mem0 ──► <data>/memory/ │
│ WaggleDB ─────► <data>/waggle.db │
│ vault ────────► <data>/vault.json │
│ connectors, channels, scheduler, marketplace, skills │
└─────────────────────────────────────────────────────────────┘
Everything runs on the user's computer. The only outside calls are the ones the user sets up: model providers, connectors, messaging channels, marketplace sources, downloads of local models and the embedding model, and analytics if the user allows them.
Parts
Web UI (apps/web)
React 19, TypeScript, Vite 6, Tailwind CSS 3.4 and Radix UI primitives. It is an application,
not a package. npm run build builds it into the root dist/, which the sidecar serves; the
desktop build uses apps/web/dist.
The UI talks to the sidecar over HTTP, with Server-Sent Events for chat streaming and
notifications. Every /api/* request carries a bearer session token. A page served by the
sidecar gets the token from GET /api/auth/session-token, which answers same-origin requests
only; the desktop window gets it through a per-launch credential from the Tauri shell.
Product analytics (PostHog) start only after the user allows them, and only in builds that carry
a key in VITE_POSTHOG_KEY (ADR-0006).
Sidecar (packages/server/src/local)
A Fastify server on Node.js. In development it runs from TypeScript source with tsx; for
release it is bundled into one service.js with esbuild. It listens on 127.0.0.1 port 3333
by default (WAGGLE_PORT, WAGGLE_HOST), rejects requests whose Host header is not local,
and serves the web UI from WAGGLE_FRONTEND_DIR or the root dist/.
It holds:
- the HTTP routes (
routes/) for chat, workspaces, sessions, memory, settings, vault, skills, plugins, connectors, marketplace, automations and the rest; - the built-in provider proxy (
routes/anthropic-proxy.ts): an OpenAI-compatible/v1/chat/completionsendpoint that translates Claude requests to Anthropic's Messages API and forwards requests for other providers to their OpenAI-compatible APIs. The agent loop and memory extraction call cloud models through it (or through LiteLLM when the user runs it); - the managed Ollama runtime (
managed-ollama-runtime.ts): downloads the official Ollama build, checks its SHA-256 and size, and runs it on127.0.0.1:11434with models in<data>/models/ollama; - the scheduler for automations (
cron.ts), notifications, held actions and approvals; - messaging channels (
channels/): Telegram, Discord, Slack, and WhatsApp throughwhatsapp-web.js(ADR-0005); - the memory store and background fact extraction (
memory-runtime.ts,memory-extraction.ts).
An optional LiteLLM proxy runs only when config.json contains "litellm": { "enabled": true },
on the user's own Python. Nothing else needs Python.
Agent runtime (packages/agent)
The agent loop (agent-loop.ts), the orchestrator that builds the system prompt and recalls
memory (orchestrator.ts), personas (persona-data.ts, personas.ts), tools, slash
commands (commands/), sub-agents and workflow templates, connectors (connectors/), MCP
client support (mcp/), the injection scanner and cost tracking (cost-tracker.ts).
Other packages
| Package | Role |
|---|---|
@waggle/core |
Config (config.json), the vault, WaggleDB (waggle.db), workspaces, file storage, embeddings, local telemetry, logger |
@waggle/shared |
Shared types, Zod schemas, the MCP server catalog |
@waggle/memory-contract |
The MemoryStore interface, record model, capability map, an in-memory store and the compatibility suite |
@waggle/memory-mem0 |
MemoryStore on the open-source mem0 library |
@waggle/marketplace |
Marketplace catalog (SQLite with full-text search), installer, security scan, sync |
@waggle/sdk |
Skill and plugin SDK, starter skills, capability packs |
@waggle/cli |
A terminal REPL on the same memory store and waggle.db |
@waggle-ai/waggle (packages/launcher) |
The server installer (install, run, doctor, update, uninstall) |
packages/team-server, packages/waggle-dance and packages/worker hold team mode. They stay
in the repository but are not built, tested in the root run, or shipped (ADR-0003).
apps/browser-ext is not part of the release.
Desktop shell (app/)
A Tauri 2 shell in Rust (app/src-tauri). There is no separate frontend in app/: the window
loads the apps/web build. The shell:
- starts the bundled sidecar with the bundled Node.js, on port 3333 or a free port if 3333 is taken, waits until it reports ready, and stops it (SIGTERM first) when the app quits;
- writes the sidecar's output to
<data>/logs/service.log; - keeps one instance running, adds a tray icon, and toggles the window with Ctrl+Shift+W;
- exposes a short list of IPC commands, allowed explicitly in
app/src-tauri/capabilities/.
A chat turn
- The UI sends
POST /api/chatwith the message, workspace and session, and reads the reply as a Server-Sent Events stream. - The orchestrator recalls memory for the message (see memory.md) and builds the system prompt from the core rules, the persona, active skills and workspace context.
- The agent loop calls the model through the built-in proxy (local Ollama models are called directly). When the model asks for a tool, the loop checks the approval rules (some actions wait for the user to approve), runs the tool, and scans the tool output for prompt injection before the model sees it. External output is passed to the model as data, never as instructions.
- Text, tool calls and approval requests stream to the UI as they happen.
- The session is appended to
<data>/workspaces/<id>/sessions/<session>.jsonl. Costs go into the execution traces inwaggle.db, and the finished turn is queued for background fact extraction.
Data
One data directory per user: WAGGLE_DATA_DIR, or ~/.waggle. install.md
lists what it contains.
- Memory goes only through
MemoryStore(@waggle/memory-contract). The shipped store keeps its SQLite files in<data>/memory/. Embeddings come from an in-process model, so memory works offline. See memory.md. waggle.dbholds Waggle's own data, which is not memory: automations, notifications, held actions, skill hashes, thumbs feedback, cost tracking, the install audit trail, the file index, and the profile card and task list per scope.- The vault (
vault.json, key in.vault-key) keeps provider keys and connector credentials, each encrypted with AES-256-GCM. - Local telemetry (
telemetry.db, off by default) and the audit log (audit.db) have their own files.
The SQLite files are opened with better-sqlite3, a native module (ADR-0008).
Models
- Provider keys. The user enters keys in Settings → Models or in the Vault. The proxy calls the provider directly from the user's computer.
- Local models. The Waggle-managed Ollama runtime, or an Ollama the user already runs
(
OLLAMA_HOST, defaulthttp://localhost:11434). - Cost tracking.
CostTrackerprices each call and the execution traces are kept inwaggle.db(ADR-0004). Settings → Models sets an optional daily budget.
Installer and server archive
The server installer (packages/launcher, ADR-0009) is one self-contained script that uses only
Node.js built-in modules. It downloads or reads a server archive, checks its SHA-256, unpacks it
into a per-user program directory and writes a waggle-server command. The command runs the
archive's own Node.js, so the user's Node.js is needed only for the first npx call.
A server archive (waggle-server-<version>-<target>.tar.gz) contains the same sidecar payload
the desktop app ships, the built web UI under web/, and a manifest.json with the version,
target and Node.js version. run starts service.js with the environment the desktop shell
uses, plus WAGGLE_FRONTEND_DIR pointing at web/.
How a release is built
Native modules (better-sqlite3, onnxruntime-node) must match the bundled Node.js, so each
target is built on its own system (ADR-0008). The desktop build scripts in app/package.json
run one staging chain into app/src-tauri/resources/:
scripts/bundle-node.mjsdownloads and verifies the pinned Node.js (22.23.2);scripts/build-sidecar.mjsbundles the sidecar intoservice.js;scripts/bundle-native-deps.mjscopies the native modules for the target;scripts/stage-sidecar-deps.mjsstages the packages the bundle keeps external;apps/webis built with Vite intoapps/web/dist;tauri buildproduces the installers:.exe(NSIS) and.msion Windows,.appand.dmgon macOS,.deband.AppImageon Linux.
Then npm run build:server-archive (scripts/build-server-archive.mjs) packs the same staged
payload and apps/web/dist into the server archive for that target, with a .sha256 next to it.
npm ci
(cd app && npm ci)
(cd app && npm run tauri:build:mac:arm64) # or tauri:build:mac:x64, tauri:build:win, tauri:build:linux
npm run build:server-archive # set TARGET_ARCH=x64 after an x64 macOS build
The Windows build must run on Windows; see docs/oss/build-windows.md.
Releases are built by .github/workflows/release.yml. On each target (Windows x64, macOS
arm64 and x64, Linux x64) it stages the sidecar, packs the server archive, builds the Tauri
bundles and smoke-tests both the server installer and the installed desktop app. A v* tag
creates a draft GitHub release with a SHA256SUMS file. The first community release is
unsigned, apart from an ad-hoc signature on macOS (docs/oss/signing.md).
Shipped dependencies are checked for licenses that allow MIT distribution
(npm run check:licenses, and cargo deny for the Rust crates), and their notices are in
THIRD_PARTY_NOTICES.md.
Extension points
- Skills: Markdown files with YAML frontmatter in
<data>/skills/, added to the system prompt when active. See guides/capabilities.md. - Plugins and MCP servers: installed from the marketplace or a local directory.
- Connectors: classes in
packages/agent/src/connectors/, registered inpackages/server/src/local/setup-connectors.ts. A connected service adds tools to the agent. - Slash commands:
CommandDefinitions inpackages/agent/src/commands/, registered with theCommandRegistry. - Memory backends: an implementation of
MemoryStorethat passes the compatibility suite in@waggle/memory-contract.
Security
The threat model, the controls and the known gaps are in THREAT_MODEL.md.
In short: the user is trusted, external content is not. Connector input, tool output and recalled
memory pass the injection scanner; secrets live in the vault; sensitive tools wait for approval;
the sidecar answers only local requests that carry the session token.