waggle-os/README.md

Waggle OS

Workspace-native AI agent platform with persistent memory, model-agnostic orchestration, and skill-extensible capabilities. It ships as a Tauri 2.0 desktop binary (Windows/macOS) with a Vite-bundled web app and a Node.js sidecar.

Architecture

waggle-os/
├── apps/
│   ├── web/            # Main web app UI (React 19 + Vite + Tailwind 4 + base-ui/react)
│   ├── www/            # Marketing site (Next.js)
│   └── browser-ext/    # Browser extension (unpacked; not an npm workspace)
├── packages/           # 28 workspace packages (see "Packages" below)
├── app/                # Tauri 2.0 desktop shell (Rust) — loads the apps/web build
├── sidecar/            # Node.js sidecar bundled into the Tauri desktop binary
└── docs/               # Architecture, contributing, threat model, and guides

Packages

The monorepo has 28 packages under packages/. They split into two groups.

Product packages (15, MIT):

Package	Purpose
agent	Agent loop, orchestrator, tools, personas, workflows, and the evolution subsystem
core	Config, the encrypted vault, cron store, file store, telemetry, and compliance/audit
server	Fastify sidecar — local (solo) and team routes, SSE streaming, Stripe, KVARK client
shared	Shared types, Zod schemas, the tier system, and the MCP catalog
marketplace	Package catalog with the SecurityGate installer
optimizer	GEPA prompt optimization
weaver	Memory consolidation daemon
waggle-dance	Multi-agent coordination protocol
worker	Background job processor (BullMQ, team mode)
sdk	Plugin / skill SDK
cli	Command-line REPL
launcher	AI-tool launcher / dock backend
admin-web	Admin dashboard for team deployments
wiki-compiler	Knowledge / wiki compiler
memory-mcp	MCP server exposing the memory substrate to external agents

Memory substrate — hive-mind-* (13, Apache-2.0): the persistent-memory core, mirrored to the public OSS repo marolinik/hive-mind.

Package	Purpose
hive-mind-core	The memory substrate: FrameStore, HybridSearch, KnowledgeGraph, IdentityLayer, AwarenessLayer, plus Harvest ingestion (src/mind + src/harvest)
hive-mind-cli	CLI for the substrate
hive-mind-mcp-server	MCP server for the substrate
hive-mind-shim-core	Signal-emitter shim library
hive-mind-wiki-compiler	Wiki compiler (OSS)
hive-mind-hooks-core	Shared hook library
hive-mind-hooks-*	Per-tool capture hooks: claude-code, claude-desktop, codex, codex-desktop, cursor, hermes, openclaw

The memory substrate is developed here and mirrored out — never the reverse. See the "Memory Substrate Sync" section of CLAUDE.md before touching packages/hive-mind-core.

Quick Start

Self-host in one line (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/marolinik/waggle-os/main/install.sh | bash

Best for a VPS or homelab — this runs a headless Waggle server (no desktop shell):

• Checks prerequisites, clones, builds, and starts the Node.js sidecar, then prints the URL (http://127.0.0.1:3333). A 5-question wizard — install dir, port, data dir, build web UI, start now — is all Enter-defaulted; pass --yes to accept every default non-interactively.
• Boots with zero API keys in echo mode so the UI works immediately. Add a provider key later under Settings → API Keys, where it is stored in the encrypted vault — keys are never passed on the command line.
• No sudo, ever. A missing prerequisite prints the exact per-OS install command and exits; the installer never installs system packages for you.

Manage the running server with the installed wrapper: scripts/waggle-server.sh status | logs | stop | start. Re-running the one-liner against an existing install prints an upgrade hint instead of reinstalling.

Run from source (development)

# Prerequisites: Node.js >= 20, npm
npm install

# (Optional) copy the env template. Provider API keys are normally set in-app
# (Settings → API Keys), which stores them in the encrypted vault — so you do
# NOT need to put keys in .env for a basic local run.
cp .env.example .env

# Terminal 1 — backend sidecar (http://localhost:3333)
npm run dev:server

# Terminal 2 — web app (http://localhost:8080)
npm run dev:web

# Open http://localhost:8080

npm run dev:server runs the Fastify sidecar via tsx (equivalent to cd packages/server && npx tsx src/local/start.ts). npm run dev:web runs the Vite dev server for apps/web.

Embeddings. By default EMBEDDING_PROVIDER=auto downloads a small in-process model (~23 MB, cached under ~/.waggle/models/) and works fully offline. For better recall — and to reproduce any hive-mind benchmark — install Ollama, run ollama pull nomic-embed-text, and set EMBEDDING_PROVIDER=ollama.

Windows: if the sidecar fails to start with an esbuild platform error, see Troubleshooting in the contributing guide.

Environment Variables

Provider keys are stored in the encrypted vault (set via Settings → API Keys) and hydrated into the process at boot, so most of these are optional for a local run. See .env.example for the full contract.

Variable	Required	Description
ANTHROPIC_API_KEY	Recommended	Claude API key. Optional in .env — can be set in-app instead (vault).
OPENAI_API_KEY	No	Enables OpenAI models and optional OpenAI embeddings.
EMBEDDING_PROVIDER	No	auto (default) · inprocess · ollama · voyage · openai · mock. auto tries in-process → Ollama → API → mock.
LITELLM_BASE_URL	No	LiteLLM proxy URL for multi-model routing (default http://localhost:4000).
DATABASE_URL	Team only	PostgreSQL connection string.
REDIS_URL	Team only	Redis for the background job queue.

Documentation

• Getting Started — first-run walkthrough
• Architecture — package structure, data flow, extension points
• Contributing — setup, tests, PR process, troubleshooting
• Threat Model — trust boundary and security controls
• Security Policy — how to report a vulnerability
• Code of Conduct

License

This repository is licensed under the MIT License, except the hive-mind-* packages under packages/, which are licensed under Apache-2.0. Each hive-mind-* package carries its own LICENSE file, which governs that package. See Packages for the split.